Adding docs around running tests and devstack

Change-Id: I28bff3a87111966532e9e3c130c2a4c51a4eb06a

doc/source/index.rst

@@ -17,6 +17,7 @@ Getting Started
    :maxdepth: 1
 
    setup/index
+   testing
    plugin/index
 
 

doc/source/setup/devstack.rst

@@ -0,0 +1,106 @@
+Running Barbican on DevStack
+===================================
+
+Currently, Barbican is not available within the default DevStack installation.
+However, you can patch a DevStack installation to include Barbican in the
+manual setup process below.
+
+It is suggested that you install DevStack into an empty VM due to the number
+of dependencies installed and configuration that is performed. With this in
+mind, we provide an easy way of running Barbican on DevStack within a Vagrant
+VM.
+
+.. warning::
+
+    This process takes anywhere from 10-30 minutes depending on your internet
+    connection.
+
+
+Easy Mode
+------------
+
+To simplify the setup process of running Barbican on DevStack, there is a
+Vagrantfile that will automatically setup up a VM containing Barbican
+running on Devstack.
+
+1. Clone the Vagrantfile collection
+
+    .. code-block:: bash
+
+        git clone https://github.com/cloudkeep/vagrantfile-collection.git
+
+2. Get into the ``barbican-devstack`` directory
+
+    .. code-block:: bash
+
+        cd vagrantfile-collection/barbican-devstack
+
+3. Start create a new VM based on the cloned configuration
+
+    .. code-block:: bash
+
+        vagrant up
+
+4. Once the VM has been successfully started and provisioned, ssh into the VM.
+
+    .. code-block:: bash
+
+        vagrant ssh
+
+5. Once inside the VM, change your directory to the ``devstack`` folder.
+
+    .. code-block:: bash
+
+        cd /opt/stack/devstack/
+
+6. Start DevStack
+
+    .. code-block:: bash
+
+        ./stack.sh
+
+
+Manual Setup
+---------------
+
+These steps assume you are running within a clean Ubuntu 14.04 virtual
+machine (local or cloud instance). If you are running locally, do not forget
+to expose the following ports
+
+#. Barbican - ``9311``
+#. Keystone API - ``5000``
+#. Keystone Admin API - ``35357``
+
+Installation
+^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+    # Install system dependencies to start DevStack and install Barbican
+    sudo apt-get update
+    sudo apt-get install -y python-pip python-dev libffi-dev libssl-dev git
+
+    # Clone DevStack and Barbican
+    git clone https://github.com/openstack-dev/devstack.git
+    git clone https://github.com/openstack/barbican.git
+
+    # Patch DevStack with Barbican setup files
+    cp barbican/contrib/devstack/lib/barbican devstack/lib/
+    cp barbican/contrib/devstack/local.conf devstack/
+    cp barbican/contrib/devstack/extras.d/70-barbican.sh devstack/extras.d/
+
+    # Copy to setup directory
+    sudo cp -R devstack/ /opt/stack/
+
+    # Create a non-root user for DevStack
+    sudo ./devstack/tools/create-stack-user.sh
+
+    # Assign permissions to that user
+    sudo chown -R stack:stack /opt/stack/
+
+    # Set the service host to localhost (Only for Local VMs)
+    sudo su - stack -c "echo \"export SERVICE_HOST=\\\"localhost\\\"\" >> .bashrc"
+
+    # Start DevStack
+    cd /opt/stack/devstack/
+    ./stack.sh

doc/source/setup/index.rst

@@ -6,4 +6,5 @@ Setting up Barbican
 
    dev
    keystone
+   devstack
    troubleshooting

doc/source/testing.rst

@@ -0,0 +1,62 @@
+Writing and Running Barbican Tests
+===================================
+
+As a part of every code review that is submitted to the Barbican project
+there are a number of gating jobs which aid in the prevention of regression
+issues within Barbican. As a result, a Barbican developer should be familiar
+with running Barbican tests locally.
+
+For your convenience we provide the ability to run all tests through
+the ``tox`` utility. If you are unfamiliar with tox please see
+refer to the `tox documentation`_ for assistance.
+
+.. _`tox documentation`: https://tox.readthedocs.org/en/latest/
+
+Unit Tests
+------------
+
+Currently, we provide tox environments for Python 2.6 and 2.7. By default
+all available test environments within the tox configuration will execute
+when calling ``tox``. If you want to run them independently, you can do so
+with the following commands
+
+.. code-block:: bash
+
+    # Executes tests on Python 2.6
+    tox -e py26
+
+    # Executes tests on Python 2.7
+    tox -e py27
+
+
+.. note::
+
+    If you do not have the appropriate Python versions available, consider
+    setting up PyEnv to install multiple versions of Python. See the
+    documentation regarding :doc:`/setup/dev` for more information.
+
+Functional Tests
+-----------------
+
+Unlike running unit tests, the functional tests require Barbican and
+Keystone services to be running in order to execute. For more
+information on :doc:`setting up a Barbican development environment
+</setup/dev>` and using :doc:`Keystone with Barbican </setup/keystone>`,
+see our accompanying project documentation.
+
+Once you have the appropriate services running and configured you can execute
+the functional tests through tox.
+
+.. code-block:: bash
+
+    # Execute Barbican Functional Tests
+    tox -e functional
+
+
+By default, the functional tox job will use ``nosetests`` to execute the
+functional tests. This is primarily due to nose being a very well known and
+common workflow among developers. It is important to note that the gating
+job will actually use ``testr`` instead of ``nosetests``. If you discover
+issues while running your tests in the gate, then consider running ``testr``
+or :doc:`Devstack</setup/devstack>` to more closely replicate the gating
+environment.