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
|
glossary
|
||||||
|
|
||||||
|
Setting up a development environment
|
||||||
|
====================================
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
development-environment
|
||||||
|
|
||||||
Running and writing tests
|
Running and writing tests
|
||||||
=========================
|
=========================
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user