b86d6b5660
This change moves existing files. It is not meant to be the final word on how the main page looks or how the other files are organized, but it gets everything roughly into shape. If the barbican team wants to make changes, please do those as follow-up patches. Note this does not touch the api directory, this one needs to be migrated to the api-ref. This is part of the docs migration work for Pike. Change-Id: Ibb9d971806964ac185882272514ee9563089d69d
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 gcc
|
|
|
|
**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
|