zaqar/doc/source/development-environment.rst

Setting up a development environment

This section describes how to setup a working Python development environment that you can use in developing Zaqar on Ubuntu or Fedora. These instructions assume that you are familiar with Git. Refer to GettingTheCode for additional information.

Virtual environments

Use virtualenv to track and manage Python dependencies for developing and testing Zaqar. Using virtualenv enables you to install Python dependencies in an isolated virtual environment, instead of installing the packages at the system level.

Note

Virtualenv is useful for development purposes, but is not typically used for full integration testing or production usage. If you want to learn about production best practices, check out the OpenStack Operations Guide.

Install GNU/Linux system dependencies

Note

This section is tested for Zaqar on Ubuntu 14.04 (Trusty) and Fedora-based (RHEL 6.1) distributions. Feel free to add notes and change according to your experiences or operating system. Learn more about contributing to Zaqar documentation in the Write the Docs! wiki.

Install the prerequisite packages.

On Ubuntu:

$ sudo apt-get install python-pip python-dev git-core

On Fedora-based distributions (e.g., Fedora/RHEL/CentOS):

$ sudo yum install python-pip python-devel git

Install MongoDB

You also need to have MongoDB installed and running.

On Ubuntu, follow the instructions in the MongoDB on Ubuntu Installation Guide.

On Fedora-based distributions, follow the instructions in the MongoDB on Red Hat Enterprise, CentOS, Fedora, or Amazon Linux Installation Guide.

Getting the code

Get the code from GitHub:

$ git clone https://github.com/openstack/zaqar.git

Configuration

1. From your home folder create the ~/.zaqar folder. This directory holds the configuration files for Zaqar:

   $ mkdir ~/.zaqar

2. Copy the Zaqar configuration samples to the directory .zaqar/:

   $ cp zaqar/etc/zaqar.conf.sample ~/.zaqar/zaqar.conf
   $ cp zaqar/etc/logging.conf.sample ~/.zaqar/logging.conf

3. Find the [drivers] section in ~/.zaqar/zaqar.conf and specify mongodb as the message store:

   storage = mongodb

4. Find the [drivers:storage:mongodb] section and modify the URI to point to your local mongod instance:

   uri = mongodb://$MONGODB_HOST:$MONGODB_PORT  # default = mongodb://localhost:27017

5. For logging, find the [DEFAULT] section in ~/.zaqar/zaqar.conf and modify as desired:

   log_file = server.log

Installing and using virtualenv

1. Install virtualenv by running:

   $ pip install virtualenv

2. Create and activate a virtual environment:

   $ virtualenv marconi
   $ source zaqar/bin/activate

3. Install Zaqar:

   $ pip install -e .

4. Start the Zaqar server:

   $ zaqar-server -v

5. Verify Zaqar is running by creating a queue:

   $ curl -i -X PUT http://localhost:8888/v1/queues/samplequeue -H "Content-type: application/json"

6. Get ready to code!

Note

You can run the Zaqar server in the foreground by passing the --nodaemon flag:

$ zaqar-server -v --nodaemon

With this method you get immediate visual feedback and it is easier to kill and restart the process.

If you do so, you have to run the cURL test (step 5) in a separate terminal.

DevStack

If you want to use Zaqar in an integrated OpenStack developing environment, you can add it to your DevStack deployment.

To do this, you first need to add the following setting to your local.conf:

enable-service zaqar-server

Then run the stack.sh script as usual.

After running the DevStack script, you can start the Zaqar server and test it by following steps 5 and 6 from the previous section.

Running unit tests

See running_tests for details.

Contributing your work

Once your work is complete, you may wish to contribute it to the project. Zaqar uses the Gerrit code review system. For information on how to submit your branch to Gerrit, see GerritWorkflow.