7992846f41
This changes adds information about how to get Zaqar code, initial configuration and how to run the zaqar-server both in a virtualenv and with DevStack to the developers manual. Change-Id: I43b2020f6ea98737baa23aa7e0a234506839f7b4
184 lines
5.4 KiB
ReStructuredText
184 lines
5.4 KiB
ReStructuredText
..
|
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
not use this file except in compliance with the License. You may obtain
|
|
a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
License for the specific language governing permissions and limitations
|
|
under the License.
|
|
|
|
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.
|
|
|
|
.. _GettingTheCode: http://wiki.openstack.org/GettingTheCode
|
|
|
|
|
|
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.
|
|
|
|
.. _virtualenv: http://pypi.python.org/pypi/virtualenv
|
|
|
|
.. 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`_.
|
|
|
|
.. _`OpenStack Operations Guide`: http://docs.openstack.org/ops/
|
|
|
|
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.
|
|
|
|
.. _`Write the Docs!`: https://wiki.openstack.org/wiki/Write_the_Docs!_(Zaqar)
|
|
|
|
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.
|
|
|
|
.. _MongoDB: http://www.mongodb.org
|
|
|
|
On Ubuntu, follow the instructions in the `MongoDB on Ubuntu Installation Guide`_.
|
|
|
|
.. _`MongoDB on Ubuntu installation guide`: http://docs.mongodb.org/manual/tutorial/install-mongodb-on-ubuntu/`
|
|
|
|
On Fedora-based distributions, follow the instructions in the
|
|
`MongoDB on Red Hat Enterprise, CentOS, Fedora, or Amazon Linux Installation Guide`_.
|
|
|
|
.. _`MongoDB on Red Hat Enterprise, CentOS, Fedora, or Amazon Linux installation guide`: http://docs.mongodb.org/manual/tutorial/install-mongodb-on-red-hat-centos-or-fedora-linux/`.
|
|
|
|
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.
|
|
|
|
.. _DevStack: http://devstack.org
|
|
|
|
Running unit tests
|
|
------------------
|
|
|
|
See :doc:`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_.
|
|
|
|
.. _GerritWorkflow: http://wiki.openstack.org/GerritWorkflow |