e2413b0fc6
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
127 lines
3.6 KiB
ReStructuredText
127 lines
3.6 KiB
ReStructuredText
Setting up a Barbican Development Environment
|
|
==============================================
|
|
|
|
These instructions are designed to help you setup a standalone version of
|
|
Barbican which uses SQLite as a database backend. This is not suitable for
|
|
production due to the lack of authentication and an interface to a secure
|
|
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.
|
|
|
|
.. 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 15.10:**
|
|
|
|
.. code-block:: bash
|
|
|
|
# Install development tools
|
|
sudo apt-get install -y git python-tox
|
|
|
|
# Install dependency build requirements
|
|
sudo apt-get install -y libffi-dev libssl-dev python-dev
|
|
|
|
**Fedora 23:**
|
|
|
|
.. code-block:: bash
|
|
|
|
# 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
|
|
--------------------------------
|
|
|
|
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 source
|
|
git clone https://git.openstack.org/openstack/barbican
|
|
cd barbican
|
|
|
|
# Create and activate a virtual environment
|
|
virtualenv .barbicanenv
|
|
source .barbicanenv/bin/activate
|
|
|
|
# Install barbican in development mode
|
|
pip install -e $PWD
|
|
|
|
Configuring Barbican
|
|
--------------------
|
|
|
|
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 </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
|