From e2413b0fc6dcd9feb1e2b08c13acd729d9eb37ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Douglas=20Mendiz=C3=A1bal?= Date: Fri, 19 Feb 2016 01:27:10 -0600 Subject: [PATCH] Simplify the development environment setup This patch simplifies the manual development environment setup documentation by omiting setup for pyenv or virtualenvwrapper. They are both very good environment management tools, but they don't play nice with each other. The updated instructions use the virtualenv package directly, and use the more straight-forward barbican-api script instead of barbican.sh Change-Id: Idf9717f18e3599839a5bf8b983b47b7802b9187c --- doc/source/setup/dev.rst | 199 +++++++++++++++++---------------------- 1 file changed, 89 insertions(+), 110 deletions(-) diff --git a/doc/source/setup/dev.rst b/doc/source/setup/dev.rst index dbc03a099..abb2025a6 100644 --- a/doc/source/setup/dev.rst +++ b/doc/source/setup/dev.rst @@ -1,4 +1,4 @@ -Setting up a Barbican development environment +Setting up a Barbican Development Environment ============================================== These instructions are designed to help you setup a standalone version of @@ -8,140 +8,119 @@ encryption system such as an HSM (Hardware Security Module). In addition, the SQLite backend has known issues with thread-safety. This setup is purely to aid in development workflows. -.. note:: +.. warning:: The default key store implementation in Barbican **is not secure** in any way. **Do not use this development standalone mode to store sensitive information!** - Installing system dependencies ----------------------------------------- +------------------------------ -**Ubuntu:** +**Ubuntu 15.10:** .. code-block:: bash - # Install dependencies required to build Barbican - sudo apt-get install -y python-pip python-dev libffi-dev libssl-dev libsqlite3-dev \ - libldap2-dev libsasl2-dev + # Install development tools + sudo apt-get install -y git python-tox - # Install dependencies required for PyEnv - sudo apt-get install -y git curl make build-essential zlib1g-dev libbz2-dev \ - libreadline-dev + # Install dependency build requirements + sudo apt-get install -y libffi-dev libssl-dev python-dev - # Install dependency for the PyEnv - virtualenvwrapper plugin - sudo pip install virtualenvwrapper - -**Fedora 22:** +**Fedora 23:** .. code-block:: bash - # Install dependencies required to build Barbican - sudo dnf install -y python-pip python-devel libffi-devel openssl-devel \ - libsq3-devel openldap-devel cyrus-sasl-devel - - # Install dependencies required for PyEnv - sudo dnf install -y git curl make gcc - - # Install dependency for the PyEnv - virtualenvwrapper plugin - sudo dnf install -y python-virtualenvwrapper - -Installing PyEnv ------------------ - -PyEnv is a great utility to simplify the management of Python versions. - -The official installation guide is available on the `PyEnv GitHub`_ page. However, -the following is a shortened guide based on a specific development workflow. - -It's important to note that this process should be done as the user that will -be operating pyenv and not the root user. - -.. _`PyEnv GitHub`: https://github.com/yyuu/pyenv#installation - -**Ubuntu:** - -.. code-block:: bash - - # Get PyEnv and virtualenvwrapper plugin source - git clone https://github.com/yyuu/pyenv.git ~/.pyenv - git clone https://github.com/yyuu/pyenv-virtualenvwrapper.git \ - ~/.pyenv/plugins/pyenv-virtualenvwrapper - - # Add PyEnv Setup to your .bashrc file - echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc - echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc - echo 'eval "$(pyenv init -)"' >> ~/.bashrc - echo 'pyenv virtualenvwrapper' >> ~/.bashrc - - # Activate PyEnv by reactivating your shell - exec $SHELL - - -Installing clean versions of Python in PyEnv ----------------------------------------------- - -Installing clean versions of Python allows for us to be able to run Barbican -unit tests through tox without much difficulty. You can see the full list of -available Python versions you can install by executing: ``pyenv install -l`` - -For the Barbican development, we'll just be installing Python 2.7.9. - -.. code-block:: bash - - # Install our Python Versions - pyenv install 2.7.9 - - # Set PyEnv to use those versions by default - pyenv global 2.7.9 + # Install development tools + sudo dnf install -y git python-tox + # Install dependency build requirements + sudo dnf install -y gcc libffi-devel openssl-devel redhat-rpm-config Setting up a virtual environment ---------------------------------- - -As we installed virtualenvwrapper earlier, we'll be using it to setup our -Barbican virtual environment. - -For more information regarding the usage of virtualenvwrapper, see the -`command reference`_ - -.. _`command reference`: http://virtualenvwrapper.readthedocs.org/en/latest/command_ref.html - -.. code-block:: bash - - # Create a virtual environment - mkvirtualenv Barbican - -.. note:: - - Virtualenvwrapper will attempt to reset the Python version that was active - when you created the virtualenv. As a result, if you have the version - 2.7.9 active when you created the virtualenv, then the default Python - version will become 2.7.9 when you reactivate the virtualenv. - - -Installing Barbican from source -------------------------------- -The running the ``barbican.sh install`` script available within the ``bin/`` -folder will copy the appropriate configuration to the ``/etc/barbican`` -directory, install all required dependencies, and start Barbican with uWSGI. +We highly recommend using virtual environments for development. You can learn +more about `Virtual Environments`_ in the Python Guide. + +If you installed tox in the previous step you should already have virtualenv +installed as well. + +.. _Virtual Environments: http://docs.python-guide.org/en/latest/dev/virtualenvs/ .. code-block:: bash - # Clone Barbican - git clone https://github.com/openstack/barbican.git + # Clone barbican source + git clone https://git.openstack.org/openstack/barbican cd barbican - # Make sure we are in our virtual environment - workon Barbican + # Create and activate a virtual environment + virtualenv .barbicanenv + source .barbicanenv/bin/activate - # Install Barbican - bin/barbican.sh install + # Install barbican in development mode + pip install -e $PWD -.. note:: +Configuring Barbican +-------------------- - It's important to note that the default configuration files do not activate - the Keystone middleware component for authentication and authorization. See - documentation on :doc:`using keystone with Barbican <./keystone>` +Barbican uses oslo.config for configuration. By default the api process will +look for the configuration file in ``$HOME/barbican.conf`` or +``/etc/barbican/barbican.conf``. The sample configuration files included in the +source code assume that you'll be using ``/etc/barbican/`` for configuration and +``/var/lib/barbican`` for the database file location. + +.. code-block:: bash + + # Create the directories and copy the config files + sudo mkdir /etc/barbican + sudo mkdir /var/lib/barbican + sudo chown $(whoami) /etc/barbican + sudo chown $(whoami) /var/lib/barbican + cp -r etc/barbican /etc + +All the locations are configurable, so you don't have to use ``/etc`` and +``/var/lib`` in your development machine if you don't want to. + +Running Barbican +---------------- + +If you made it this far you should be able to run the barbican development +server using this command: + +.. code-block:: bash + + bin/barbican-api + +An instance of barbican will be listening on ``http://localhost:9311``. Note +that the default configuration uses the unauthenticated context. This means +that requests should include the ``X-Project-Id`` header instead of including +a keystone token in the ``X-Auth-Token`` header. For example: + +.. code-block:: bash + + curl -v -H 'X-Project-Id: 12345' \ + -H 'Accept: application/json' \ + http://localhost:9311/v1/secrets + +For more information on configuring Barbican with Keystone auth see the +:doc:`Keystone Configuration ` page. + +Building the Documentation +-------------------------- + +You can build the html developer documentation using tox: + +.. code-block:: bash + + tox -e docs + + +Running the Unit Tests +---------------------- + +You can run the unit test suite using tox: + +.. code-block:: bash + + tox -e py27