Docs changes

Change-Id: Id18c19ed5089a306bbac263a07d7f6e162e43052

docs/source/topics/dev_notes/addingowndistro.rst

@@ -28,7 +28,7 @@ we can add in your own distribution support.
     are bootstrapping rhel (and how we are detecting rhel) for an example.
 
 **conf/distros**
-  This set of yaml files contains defintions for what packages, 
+  This set of yaml files contains definitions for what packages, 
   what pip to package mappings and what code entrypoints are used
   when setting up a given component. The critical key here is the
   ``platform_pattern`` key which is used as a regular expression to

docs/source/topics/dev_notes/architecture.rst

@@ -21,7 +21,7 @@ setup toolkit. Since the existing `devstack <http://devstack.org/>`_ did (and st
 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. 
+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*.
@@ -57,13 +57,13 @@ Anvil is designed to have the following set of software components:
     * Unconfiguring
     * Pre-uninstalling
     * Uninstalling previously installed packages
-    * Post-uninstalling 
+    * Post-uninstalling
 
   * Starting
 
     * Pre-starting
     * Starting
-    * Post-starting 
+    * Post-starting
 
   * Stopping
   * Testing
@@ -123,6 +123,3 @@ Anvil is designed to have the following set of software components:
   (if the component supports this concept) as well as which distribution the persona supports (if
   there is a desire to restrict a given persona to a given distribution this field can be
   used to accomplish that goal).
-
-
- 

docs/source/topics/examples.rst

@@ -5,6 +5,11 @@
 Examples
 ========
 
+Pre-installing
+--------------
+
+See [Getting started! pre-setup] [gs] section to make the right preparation.
+
 Bootstrapping
 -------------
 
@@ -150,4 +155,5 @@ Uninstalling
    :language: none
    :linenos:
 
-   
+
+[gs]: /en/latest/topics/gettingstarted.html#pre-setup

docs/source/topics/features.rst

@@ -5,63 +5,97 @@
 Features
 ========
 
--  A set of configuration files (in yaml format) that shows common/component/distribution configurations.
+Configurations
--  Supports the following *actions* on the various `OpenStack`_ components.
+--------------
 
-   * **Installing**:
+A set of configuration files (in yaml format) that shows common/component/distribution configurations.
+All the yaml configuration files could be found in:
 
-     * Automatically downloading source from git and performing tag/branch checkouts.
+* conf/templates/keystone/
-     * Automatically verifying and translating requirement files to known `pypi`_/rpm packages.
+* conf/components/
-     * Automatically installing and building missing dependencies (`pypi`_ and rpm) for you.
+* conf/distros/
-     * Automatically configuring the needed files, symlinks, adjustments, and any patches.
+* subdirectories of conf/personas/
 
-   * **Starting**: starting of the components sub-programs with
-     the needed configuration via the common `daemon`_ model.
 
-     * Also creates a ``pid``, ``stderr`` and ``stdout`` file set for debugging/examination.
+Installing
+----------
 
-   * **Stopping**: stopping of the previously started components.
+* Automatically downloading source from git and performing tag/branch checkouts.
-   * **Uninstalling**: getting you back to an initial 'clean' state.
+* 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.
 
-     * Removing installed configuration.
+Testing
-     * Undoing of installed files/directories.
+-------
-     * Removing of packages installed.
 
-   * **Testing**: automatically running each components unit tests.
+Automatically running each component unit tests.
-   * **Packaging**: creating a basic set of packages that matches the components selected.
-   
-     - Supports automatic injection of dependencies and creation of a ``changelog`` from git history.
-   
-   * **Status**: checking the status of the running components sub-programs
 
--  Supports **dry-run** mode (to see what *would* happen).
+Starting
--  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.
+Starting of the components sub-programs with the needed configuration via the common `daemon`_ model.
-   * 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).
+* Also creates a ``pid``, ``stderr`` and ``stdout`` file set for debugging/examination.
--  Extensive **logging** (and debug mode)
+* Trace files could be found in $HOME/openstack/<component>/traces/
 
-   * All commands executed are logged, all configuration files read/written (and so on).
+Stopping
+--------
 
--  **Package tracking and building**
+Stopping of the previously started components.
 
-   * Creation of a single rpm of your installation. 
+Uninstalling
+------------
 
-     * This freezes what is needed
+Getting you back to an initial 'clean' state:
-       for that release to a known set of packages and dependencies.
 
-   * Automatically building and/or including all needed dependencies.
+* Removing installed configuration.
+* Undoing of installed files/directories.
+* Removing of packages installed.
 
-     * Includes application of your distributions native packages (when applicable).
+Packaging
+---------
 
-.. _epel: http://fedoraproject.org/wiki/EPEL
+* Ceating a basic set of packages that matches the components selected.
-.. _forking: http://users.telenet.be/bartl/classicperl/fork/all.html
+* Supports automatic injection of dependencies and creation of a ``changelog`` from git history.
-.. _screen: http://www.manpagez.com/man/1/screen/
+
-.. _upstart: http://upstart.ubuntu.com/
+Status
-.. _OpenStack: http://openstack.org/
+------
-.. _pypi: http://pypi.python.org/pypi
+
-.. _daemon: http://en.wikipedia.org/wiki/Daemon_(computing)
+* Checking the status of the running components sub-programs
+
+Dry run
+-------
+
+``dry_run`` satisfied with any action it turns verbose and all modifying the outside world calls (running external commands, kill, mkdir ......) are not executing.
+
+Pythonic
+--------
+
+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.
+* Supports installation personas that define what is to be installed, thus decoupling the 'what' from the 'how'.
+
+Resumption
+----------
+
+Install/start/stop resumption so that when you install you can ``ctrl+c`` and resume later (where applicable).
+
+Extensive logging
+-----------------
+
+* All commands executed are logged in standard output, all configuration files read/written (and so on).
+* Debug mode could be activate with ``-v`` option
+
+Package tracking and building
+-----------------------------
+
+
+* 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).

docs/source/topics/gettingstarted.rst

@@ -81,9 +81,9 @@ instances won’t have a `tty`_).
 
 ::
 
-    $ sudo visudo 
+    $ sudo visudo
 
-Then comment out line:
+Then comment out line
 
 ::
 
@@ -95,32 +95,32 @@ Also disable selinux:
 
      $ sudo vi /etc/sysconfig/selinux
 
-Change *SELINUX=enforcing* to *SELINUX=disabled* then reboot.
+Change `SELINUX=enforcing` to `SELINUX=disabled` then reboot.
 
 ::
 
      $ sudo reboot
 
-Also to avoid qemu errors please follow the solution @ https://bugs.launchpad.net/anvil/+bug/985786
+Create specifc user to isolate all the Anvil processes from root user
-which will ensure that the ``qemu`` user can write to your instances directory. If needed edit ``conf/components/nova.yaml``
-and also adjust the ``instances_path`` option.
-
-This can be typically solved by running the following (and then updating the ``instances_path`` option)
 
 ::
 
-    $ sudo mkdir -pv /home/openstack
+    $ sudo useradd <username>
-    $ sudo chmod -R a+rwx /home/openstack
+    $ sudo passwd <username>
 
-Also as documented at http://docs.openstack.org/essex/openstack-compute/admin/content/qemu.html#fixes-rhel-qemu
+Set user as sudoer
-please run the following (**after** installation).
 
 ::
 
-    $ setsebool -P virt_use_execmem on
+    $ sudo visudo
-    $ sudo ln -s /usr/libexec/qemu-kvm /usr/bin/qemu-system-x86_64
-    $ sudo service libvirtd restart
 
+Add `<username>     ALL=(ALL)       ALL`
+
+Make all the rest of actions as <username> user
+
+::
+
+    $ sudo su - <username>
 
 Get git!
 --------
@@ -138,6 +138,8 @@ We’ll grab the latest version of ANVIL via git:
 ::
 
     $ git clone git://github.com/stackforge/anvil.git
+    $ cd anvil
+    $ git fetch origin <stable/version>
 
 
 Configuration
@@ -145,8 +147,10 @@ Configuration
 
 Any configuration to be updated should now be done.
 
-Please edit the corresponding files in ``conf/components/`` or ``conf/components/personas``
+Please edit the corresponding yaml files in ``conf/components/`` or ``conf/components/personas``
 to fit your desired configuration of nova/glance and the other OpenStack components.
+You can use ``-p <conf/components/required_file.yaml>`` option with following commands
+to use configuration files.
 
 If you are using a ``FlatManager`` and RH/Fedora then you might want to read and follow:
 
@@ -204,6 +208,23 @@ You should see a set of distribution packages and/or pips being
 installed and configuration files being written as ANVIL figures out how to
 install your desired components from the prepared packages built in the last
 step (if you desire more informational output add a ``-v`` to that command).
+``-p`` option is actual too. You can specify conf file just like in ``prepare`` action.
+Without specified conf file command will execute with conf/personas/in-a-box/basic.yaml
+
+
+Also to avoid qemu errors please follow the solution @ https://bugs.launchpad.net/anvil/+bug/985786
+which will ensure that the ``qemu`` user can write to your instances directory. If needed edit ``conf/components/nova.yaml``
+and also adjust the ``instances_path`` option.
+
+Also as documented at http://docs.openstack.org/essex/openstack-compute/admin/content/qemu.html#fixes-rhel-qemu
+please run the following (**after** installation).
+
+::
+
+    $ setsebool -P virt_use_execmem on # optional
+    $ sudo ln -s /usr/libexec/qemu-kvm /usr/bin/qemu-system-x86_64
+    $ sudo service libvirtd restart
+
 
 Testing
 ----------

docs/source/topics/qanda.rst

@@ -9,7 +9,7 @@ How do I cause the anvil dependencies to be reinstalled?
 
 Anvil bootstraps itself via shell script (if you look at the code
 in the file ``smithy`` you will see that it is actually a bash
-script). 
+script).
 
 This bootstrapping occurs to ensure that anvils pypi/rpm/deb
 dependencies are installed before anvil can actually be used. 
@@ -20,7 +20,7 @@ and at ``$PWD/.anvil_bootstrapped`` to cause bootstrapping to occur again.
 Another way to make this happen temporarily is to use the following:
 
 ::
-    
+
     sudo BOOT_FILES=/dev/null ./smithy
 
 This will make anvil think those files are coming from ``/dev/null``
@@ -49,7 +49,7 @@ An example of this, lets adjust nova to use the ``stable/essex`` branch.
     # Where we download this from...
     get_from: "git://github.com/openstack/nova.git?branch=stable/essex"
 
-    
+
 - The special keywords here are ``branch=``
   and ``tag=`` which are ways for anvil to parse out which branch/tag
   you desire. 
@@ -57,7 +57,7 @@ An example of this, lets adjust nova to use the ``stable/essex`` branch.
   - **Note:** this is not git official syntax
   - **Note:** tag overrides branch (so you can't really include both)
 
-     
+
 `OMG` the images take forever to download!
 ------------------------------------------
 
@@ -85,4 +85,4 @@ This will remove the larger ubuntu image and just use the smaller `cirros`_ imag
 Note that repeated downloads occur due to the fact that the files inside the image do not match the name of what is installed
 into glance (this can be avoided by completely disabling the image uploading, see the persona file for the flag for this).
 
-.. _cirros: https://launchpad.net/cirros
+.. _cirros: https://launchpad.net/cirros

docs/source/topics/solvedproblems.rst

@@ -1,20 +0,0 @@
-.. _solved-problems:
-
-===============
-Solved Problems
-===============
-
-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.
-
-Issue @ https://github.com/pypa/pip/issues/982