Setting up a development environment docs
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
This commit is contained in:
Victoria Martínez de la Cruz
parent
c3151ea051
commit
7992846f41
184
doc/source/development-environment.rst
Normal file
184
doc/source/development-environment.rst
Normal file
@ -0,0 +1,184 @@
|
||||
..
|
||||
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
|
||||
@ -80,6 +80,13 @@ Concepts
|
||||
|
||||
glossary
|
||||
|
||||
Setting up a development environment
|
||||
====================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
development-environment
|
||||
|
||||
Running and writing tests
|
||||
=========================
|
||||
|
||||
Loading…
Reference in New Issue
Block a user