diff --git a/doc/source/development-environment.rst b/doc/source/development-environment.rst new file mode 100644 index 000000000..e9e528416 --- /dev/null +++ b/doc/source/development-environment.rst @@ -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 \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst index 52363c701..c4de67b11 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -80,6 +80,13 @@ Concepts glossary +Setting up a development environment +==================================== + +.. toctree:: + :maxdepth: 1 + + development-environment Running and writing tests =========================