diff --git a/docs/source/index.rst b/docs/source/index.rst index 77b52ffa..86afdaf6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,7 +4,7 @@ ANVIL Documentation ===================== -.. rubric:: Everything about ANVIL, a set of **python** scripts and utilities to forge raw openstack into a productive tool! +.. rubric:: Everything about ANVIL, a set of **python** scripts and utilities to forge raw openstack into a productive tool! ---- diff --git a/docs/source/topics/bugshugscode.rst b/docs/source/topics/bugshugscode.rst index 239a46c0..a296c336 100644 --- a/docs/source/topics/bugshugscode.rst +++ b/docs/source/topics/bugshugscode.rst @@ -26,7 +26,12 @@ The source code is on github located at: https://github.com/stackforge/anvil/ -Feel free to fork it and contribute to it. You can also get a tarball or zip archive of the code. +Feel free to fork it and contribute to it. + +Bugs +---- + +https://bugs.launchpad.net/anvil Branches -------- @@ -39,9 +44,9 @@ https://github.com/stackforge/anvil/branches Hacking ======= -Feel free to hack but please try to follow the `hacking guidelines`_ +Feel free to hack but please try to follow the `hacking guidelines`_. .. _apache version 2.0 license: https://github.com/stackforge/anvil/blob/master/LICENSE .. _launchpad’s issue tracking system: http://launchpad.net/anvil -.. _hacking guidelines: https://github.com/stackforge/anvil/blob/master/README.md +.. _hacking guidelines: https://github.com/stackforge/anvil/blob/master/HACKING.md diff --git a/docs/source/topics/dev_notes/addingowndistro.rst b/docs/source/topics/dev_notes/addingowndistro.rst index 74511f90..a9208a81 100644 --- a/docs/source/topics/dev_notes/addingowndistro.rst +++ b/docs/source/topics/dev_notes/addingowndistro.rst @@ -70,16 +70,3 @@ we can add in your own distribution support. After adding make sure you reference them in your **conf/distros** yaml file so that the correct subclass will be used. If you are going to want to create package files from the installed code then you will need to hook-in to a file similar to the rpm module that exists there. - -Bring back the dead! ----------- - -If you are adding in debian/ubuntu/fedora support please check out the older code that existed that did this -which was removed due to it being unmatained. It might help ease the process if these files are just brought -back from the dead and fixed as needed... - -+ https://github.com/yahoo/Openstack-Anvil/blob/2012.5.11/anvil/packaging/apt.py -+ https://github.com/yahoo/Openstack-Anvil/blob/2012.5.11/anvil/distros/oneiric.py -+ https://github.com/yahoo/Openstack-Anvil/blob/2012.5.11/conf/distros/ubuntu-oneiric.yaml -+ https://github.com/yahoo/Openstack-Anvil/blob/2012.5.11/conf/distros/fedora-16.yaml - diff --git a/docs/source/topics/dev_notes/architecture.rst b/docs/source/topics/dev_notes/architecture.rst index 34f54c0f..df7b526d 100644 --- a/docs/source/topics/dev_notes/architecture.rst +++ b/docs/source/topics/dev_notes/architecture.rst @@ -1,8 +1,8 @@ .. _architecture: -==== -How anvil is architected. -==== +======================== +How anvil is architected +======================== This little ``HOWTO`` can be used by those who wish to understand how anvil does things and why some of its @@ -11,48 +11,52 @@ architectural decisions were made. Diving in! ---------- -^^^^^^^^^^ +^^^^^^^^^^^^^^^^ A little history -^^^^^^^^^^ +^^^^^^^^^^^^^^^^ Once upon a time there was a idea of replacing the then existing `devstack `_ with a more robust, more error-tolerant and more user/developer friendly OpenStack setup toolkit. Since the existing `devstack `_ did (and still -does not support very well) complex intercomponent (and interpackage management system) dependencies, -and installing/starting/stopping/uninstalling of OpenStack components it was thought -that there could be a toolkit that could handle this better. It would also be in -Python the language of choice for the rest of the OpenStack components thus making -it easier to understand for programmers who are already working in OpenStack code. -Never fear though, it was meant to be used by those who actually wanted to understand -the setup of OpenStack by looking at similar code but this was targeted as not being -a necessity. Thus *devstack2* was born which was later renamed *devstack.py* and after a -little while once again got renamed to *anvil*. +does not support very well) complex intercomponent (and interpackage management system) dependencies +and installing/packaging/starting/stopping/uninstalling of OpenStack components. -^^^^^^^^^^ +To solve this problem it was thought that there could be a toolkit that could handle this better. +It would also be in Python the language of choice for the rest of the OpenStack components thus making +it easier to understand for programmers who are already working in OpenStack code. Thus *devstack2* was +born which was later renamed *devstack.py* and after a little while once again got renamed to *anvil*. + +^^^^^^^^^ Structure -^^^^^^^^^^ +^^^^^^^^^ Anvil is designed to have the following set of software components: * **Actions:** an action is a sequence of function calls on a set of implementing classes which follows a logically flow from one step to the next. At the end of each step an action may choose to negate a step of another action. - *The currently implemented actions and stages are the following*: + + * Preparing + + * Downloading source code + * Post-download patching of the source code + * Deep dependency & requirement analysis + * Downloading and packaging of missing python dependencies + * Packaging downloaded source code + * Creation of a repository with all built packages & dependencies * Install - * Downloading - * Post-download patching * Configuring * Pre-installing - * Installing + * Installing packages from previously prepared repository * Post-installing * Uninstall * Unconfiguring * Pre-uninstalling - * Uninstalling + * Uninstalling previously installed packages * Post-uninstalling * Starting @@ -71,14 +75,16 @@ Anvil is designed to have the following set of software components: into a file so that if ``ctrl-c`` aborts anvil and later the install is restarted anvil can notice that the previous phases have already been completed and those phases can be skipped. This is how anvil does action and step resuming. + * **Components:** a component is a class which implements the above steps (which are literally methods on an instance) and is registered with the persona and configuration to be activated. To aid in making it easier to add in new components a set of *generic* base classes exist that provide common functionality that should work in most simplistic installs. These can be found in - ``anvil/components/__init__.py``. All current components that exist either use + ``anvil/components/``. All current components that exist either use these base classes directly or inherit from them and override functions to provide additional capabilities needed to perform the specified action. + * **Distributions:** a distribution is a yaml file that is tied to a operating system distribution and provides references for components to use in a generic manner. Some of these references include how to map a components ``pip-requires`` @@ -86,12 +92,13 @@ Anvil is designed to have the following set of software components: or ``apt``) or what non-specified dependencies are useful in getting the component up and running (such as ``guestfish`` for image mounting and manipulation). Other helpful references include allowing for components to specify standard - identifiers for configuration such as ``pip`` but the underlying yaml file can + identifiers for configuration such as ``pip``. This allows the underlying yaml file to map the ``pip`` command to a distribution-centric command (in RHEL it its really named ``pip-python``), see the *commands* key in the yaml files for examples of these settings. Note that each distribution yaml file that exists in ``conf/distros`` provides this set of references for each component and gets selected based on the yaml key in that file named *platform_pattern*. + * **Configuration:** central to how anvil operates is the ability to be largely configuration driven (code when you need it but avoid it if you can). Distributions as seen by the ``conf/distros`` folder specify @@ -103,7 +110,8 @@ Anvil is designed to have the following set of software components: configuration drive approach (as much as can be possible) was a key design goal that drives how anvil was and is developed. It has even seemed to be ahead of its time due to how anvil has a distribution yaml file that has specified component dependencies - long before the OpenStack community even recgonized such a dependency list was useful. + long before the OpenStack community even recognized such a dependency list was useful. + * **Personas:** a persona is a way for anvil to know what components (and possibly subsystems of those components) you wish to have the given action applied to. Since not everyone can agree on what is an install of OpenStack this concept allows for diff --git a/docs/source/topics/features.rst b/docs/source/topics/features.rst index f147466f..d5e0af3d 100644 --- a/docs/source/topics/features.rst +++ b/docs/source/topics/features.rst @@ -11,26 +11,26 @@ Features * **Installing**: * Automatically downloading source from git and performing tag/branch checkouts. - * Automatically verifying and translating ``test-requires`` and ``pip-requires`` files to known `pypi`_/rpm packages. - * Automatically installing and building dependencies/packaging (`pypi`_ and rpm) specifics for you. - * Automatically configuring the needed files, symlinks, adjustments, tweaks. + * Automatically verifying and translating requirement files to known `pypi`_/rpm packages. + * Automatically installing and building missing dependencies (`pypi`_ and rpm) for you. + * Automatically configuring the needed files, symlinks, adjustments, and any patches. * **Starting**: starting of the components sub-programs with - the needed configuration via the common `daemon`_ model + the needed configuration via the common `daemon`_ model. * Also creates a ``pid``, ``stderr`` and ``stdout`` file set for debugging/examination. - * **Stopping**: stopping of the previously started components - * **Uninstalling**: getting you back to an initial 'clean' state + * **Stopping**: stopping of the previously started components. + * **Uninstalling**: getting you back to an initial 'clean' state. * Removing installed configuration. * Undoing of installed files/directories. * Removing of packages installed. - * **Testing**: running each components unit tests (and in the future performing a simple set of integration tests) - * **Packaging**: creating a basic set of packages that matches the components selected + * **Testing**: automatically running each components unit tests. + * **Packaging**: creating a basic set of packages that matches the components selected. - - Supports automatic injection of dependencies, creation of change log from git history. + - Supports automatic injection of dependencies and creation of a ``changelog`` from git history. * **Status**: checking the status of the running components sub-programs @@ -38,25 +38,25 @@ Features - Written in **python** so it matches the style of other `OpenStack`_ components. - **Code decoupling** (thus encouraging re-use by others) - * Components/actions are isolated as individual classes... + * Components & actions are isolated as individual classes. * Supports installation *personas* that define what is to be installed, thus decoupling the 'what' from the 'how'. - **Install/start/stop... resumption** so that when you install you can ``ctrl+c`` and resume later (where applicable). - Extensive **logging** (and debug mode) - * All commands ran are logged, all configuration files read/write... + * All commands executed are logged, all configuration files read/written (and so on). - **Package tracking and building** - * Anvil can create a single rpm of your installation, as well as build or include all needed dependencies so that - the software that is installed can be installed repeatedly and reliably in the future. - * This allows for installations to use the distributions native packages (when applicable) - as well as provides a list of pips which should be packaged by that distribution before the given `OpenStack`_ release - is stabilized. - * This also allows for releases of anvil to track exactly how (and what packages and what mapping) is needed for a given - release tag (which maps to a given `OpenStack`_ release tag), thus freezing what is needed for that release to a - known set. + * Creation of a single rpm of your installation. + + * This freezes what is needed + for that release to a known set of packages and dependencies. + + * Automatically building and/or including all needed dependencies. + + * Includes application of your distributions native packages (when applicable). .. _epel: http://fedoraproject.org/wiki/EPEL .. _forking: http://users.telenet.be/bartl/classicperl/fork/all.html diff --git a/docs/source/topics/solvedproblems.rst b/docs/source/topics/solvedproblems.rst index ed157640..d1feae76 100644 --- a/docs/source/topics/solvedproblems.rst +++ b/docs/source/topics/solvedproblems.rst @@ -4,12 +4,15 @@ Solved Problems =============== - -Solutions -========= - -Mysql user denied +MySQL user denied ----------------- This seems common and can be fixed by running one of the steps at http://dev.mysql.com/doc/refman/5.0/en/resetting-permissions.html + +The temporary folder for building (/tmp/XYZ) is not owned by your user! +----------------------------------------------------------------------- + +This is a new feature of pip>=1.3 where it seems to incorrectly handle the SUDO +user. To get around this just remove the above directory and reactivate the +appropriate ANVIL command.