keystone/doc/source/devref/development.environment.rst

Setting up a Keystone development environment

This document describes getting the source from keystone's Git repository for development purposes.

To install Keystone from packaging, refer instead to Keystone's User Documentation.

Prerequisites

This document assumes you are using Ubuntu, Fedora or openSUSE (SLE)

And that you have the following tools available on your system:

• Python 2.7 and 3.4
• git
• setuptools
• pip
• msgfmt (part of the gettext package)
• virtualenv

Reminder: If you're successfully using a different platform, or a different version of the above, please document your configuration here!

Getting the latest code

Make a clone of the code from our `Git repository`:

$ git clone https://git.openstack.org/openstack/keystone.git

When that is complete, you can:

$ cd keystone

Installing dependencies

Keystone maintains two lists of dependencies:

requirements.txt
test-requirements.txt

The first is the list of dependencies needed for running keystone, the second list includes dependencies used for active development and testing of Keystone itself.

These dependencies can be installed from PyPi using the Python tool pip.

However, your system may need additional dependencies that pip (and by extension, PyPi) cannot satisfy. These dependencies should be installed prior to using pip, and the installation method may vary depending on your platform.

Ubuntu 14.04:

$ sudo apt-get install python-dev python3-dev libxml2-dev libxslt1-dev \
    libsasl2-dev libsqlite3-dev libssl-dev libldap2-dev libffi-dev

Fedora 19+:

$ sudo yum install python-lxml python-greenlet-devel python-ldap sqlite-devel openldap-devel python-devel libxslt-devel openssl-devel libffi-devel

openSUSE 13.2 (SLE 12):

$ sudo zypper install libxslt-devel openldap2-devel libopenssl-devel python-devel python-greenlet-devel python-ldap python-lxml python-pysqlite sqlite3-devel

PyPi Packages and VirtualEnv

We recommend establishing a virtualenv to run Keystone within. virtualenv limits the Python environment to just what you're installing as dependencies, useful to keep a clean environment for working on Keystone. The tools directory in Keystone has a script already created to make this very simple:

$ python tools/install_venv.py

This will create a local virtual environment in the directory .venv. Once created, you can activate this virtualenv for your current shell using:

$ source .venv/bin/activate

The virtual environment can be disabled using the command:

$ deactivate

You can also use tools\with_venv.sh to prefix commands so that they run within the virtual environment. For more information on virtual environments, see virtualenv.

If you want to run Keystone outside of a virtualenv, you can install the dependencies directly into your system from the requirements files:

# Install the dependencies for running keystone
$ pip install -r requirements.txt

# Install the dependencies for developing, testing, and running keystone
$ pip install -r test-requirements.txt

# Use 'python setup.py' to link Keystone into Python's site-packages
$ python setup.py develop

Verifying Keystone is set up

Once set up, either directly or within a virtualenv, you should be able to invoke Python and import the libraries. If you're using a virtualenv, don't forget to activate it:

$ source .venv/bin/activate

You should then be able to import keystone using Python without issue:

$ python -c "import keystone"

If you can import Keystone without a traceback, you should be ready to move on to ../developing.