openstack/barbican
Code Issues Proposed changes

Simplify the development environment setup

Browse Source 
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
This commit is contained in:
Douglas Mendizábal 2016-02-19 01:27:10 -06:00 committed by Douglas Mendizábal
parent c6bc39a3a9
commit e2413b0fc6
1 changed files with 89 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

199
doc/source/setup/dev.rst
View File

@ -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 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 the SQLite backend has known issues with thread-safety. This setup is purely
to aid in development workflows. to aid in development workflows.
.. note:: .. warning::
The default key store implementation in Barbican **is not secure** in The default key store implementation in Barbican **is not secure** in
any way. **Do not use this development standalone mode to store sensitive any way. **Do not use this development standalone mode to store sensitive
information!** information!**
Installing system dependencies Installing system dependencies
---------------------------------------- ------------------------------
**Ubuntu:** **Ubuntu 15.10:**
.. code-block:: bash .. code-block:: bash
# Install dependencies required to build Barbican # Install development tools
sudo apt-get install -y python-pip python-dev libffi-dev libssl-dev libsqlite3-dev \ sudo apt-get install -y git python-tox
libldap2-dev libsasl2-dev
# Install dependencies required for PyEnv # Install dependency build requirements
sudo apt-get install -y git curl make build-essential zlib1g-dev libbz2-dev \ sudo apt-get install -y libffi-dev libssl-dev python-dev
libreadline-dev
# Install dependency for the PyEnv - virtualenvwrapper plugin **Fedora 23:**
sudo pip install virtualenvwrapper
**Fedora 22:**
.. code-block:: bash .. code-block:: bash
# Install dependencies required to build Barbican # Install development tools
sudo dnf install -y python-pip python-devel libffi-devel openssl-devel \ sudo dnf install -y git python-tox
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 dependency build requirements
sudo dnf install -y gcc libffi-devel openssl-devel redhat-rpm-config
Setting up a virtual environment 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/`` We highly recommend using virtual environments for development. You can learn
folder will copy the appropriate configuration to the ``/etc/barbican`` more about `Virtual Environments`_ in the Python Guide.
directory, install all required dependencies, and start Barbican with uWSGI.
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 .. code-block:: bash
# Clone Barbican # Clone barbican source
git clone https://github.com/openstack/barbican.git git clone https://git.openstack.org/openstack/barbican
cd barbican cd barbican
# Make sure we are in our virtual environment # Create and activate a virtual environment
workon Barbican virtualenv .barbicanenv
source .barbicanenv/bin/activate
# Install Barbican # Install barbican in development mode
bin/barbican.sh install pip install -e $PWD
.. note:: Configuring Barbican
--------------------
It's important to note that the default configuration files do not activate Barbican uses oslo.config for configuration. By default the api process will
the Keystone middleware component for authentication and authorization. See look for the configuration file in ``$HOME/barbican.conf`` or
documentation on :doc:`using keystone with Barbican <./keystone>` ``/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 </setup/keystone>` 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