diff --git a/doc/source/index.rst b/doc/source/index.rst index 77c1a203f..840cdf207 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -17,6 +17,7 @@ Getting Started :maxdepth: 1 setup/index + testing plugin/index diff --git a/doc/source/setup/devstack.rst b/doc/source/setup/devstack.rst new file mode 100644 index 000000000..9a14be3b0 --- /dev/null +++ b/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 diff --git a/doc/source/setup/index.rst b/doc/source/setup/index.rst index 68664f76c..cfe719c73 100644 --- a/doc/source/setup/index.rst +++ b/doc/source/setup/index.rst @@ -6,4 +6,5 @@ Setting up Barbican dev keystone + devstack troubleshooting diff --git a/doc/source/testing.rst b/doc/source/testing.rst new file mode 100644 index 000000000..7ccff052a --- /dev/null +++ b/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 +` and using :doc:`Keystone with Barbican `, +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` to more closely replicate the gating +environment.