Merge "Adding getting-started docs"

doc/architecture/index.rst

@@ -1,7 +1,7 @@
 .. _architecture:
 
 Architecture
-==================
+============
 
 .. toctree::
    :maxdepth: 2

doc/architecture/logical.rst

@@ -1,6 +1,6 @@
-=============
+====================
 Logical architecture
-=============
+====================
 
 See information for each component for more information.
 

doc/config.rst

@@ -1,3 +1,9 @@
+.. _configuration:
+
+=============
+Configuration
+=============
+
 Configuration of Services
 =========================
 

doc/getting-started.rst

@@ -4,8 +4,271 @@ Getting started
 
 Libra is a system to provide LoadBalancing as a Service on top of
 various platforms. It is comprised of four components :ref:`libra-api`,
-:ref:`libra-admin-api`, :ref:`libra-pool-mgr` and :ref:`libra-worker`,
+:ref:`libra-admin-api`, :ref:`libra-pool-mgm` and :ref:`libra-worker`,
 supported by a few other open source components. For more information see
 :doc:`architecture/index`.
 
 
+Development environment
++++++++++++++++++++++++
+This guide will walk you through howto setup a development environment for Libra
+using:
+
+* 1 Node for the API, Admin API and Pool mgm with MySQL
+* n+ Nodes for workers that is going to run HAProxy
+* Ubuntu 12.04 as our OS of choice
+
+Common steps
+============
+
+1. Install general system dependencies
+
+::
+
+    $ sudo apt-get install -qy python-virtualenv python-pip python-dev git gcc
+
+2. Clone the repo from Stackforge at GitHub
+
+::
+
+    $ git clone ssh://git@github.com/stackforge/libra
+    $ cd libra
+
+3. Create needed directories
+
+::
+
+    $ sudo mkdir -p /var/run/libra /var/log/libra
+    $ sudo chown ubuntu:ubuntu /var/run/libra /var/log/libra
+
+
+Installing
+==========
+
+.. index::
+    double: install; libra
+
+1. Do steps in :ref:`ppa`
+
+2. Do steps in 'Common steps'
+
+3. Install dependencies
+
+::
+
+    $ sudo apt-get install -qy gearman-jobs-server mysql-server
+
+4. Setup a VirtualEnvironment
+
+.. note::
+
+    This is to not interfere with systemwide libraries.
+
+::
+
+    $ virtualenv .venv
+    $ . .venv/bin/active
+
+5. Install python-gearman
+
+.. note::
+
+    This is a custom version with patches commited upstream but not release yet.
+
+   sudo pip install  https://launchpad.net/~libra-core/+archive/ppa/+files/gearman_2.0.2.git2.orig.tar.gz
+
+6. Install dependencies using pip
+
+::
+
+    $ pip install -r requirements.txt -r test-requirements.txt
+
+
+7. Install python-keystoneclient
+
+::
+    pip install python-keystoneclient
+
+8. Install Libra in development mode
+
+::
+
+    $ python setup.py develop
+
+9. Copy the configuration file to /etc
+
+::
+
+    $ sudo cp etc/sample_libra.cfg /etc/libra.cfg
+
+10. Change running as libra to ubuntu
+
+.. note::
+
+    This is to not have to add a new user.
+
+::
+
+    $ sudo sed -r -i 's/^(group|user).*libra/\1 = ubuntu/' /etc/libra.cfg
+
+11. Configure libra
+
+::
+
+    $ sudo vi /etc/libra.cfg
+
+.. note::
+
+   See :ref:`configuration` for how to proceed for various options.
+
+   You should at least configure the variables needed for your environment.
+
+
+Setup database and gearman
+==========================
+1. Import the initial database
+
+::
+
+    $ mysql < libra/common/api/lbaas.sql
+
+2. Change the listening address of Gearman server
+
+::
+
+    $ sudo vi /etc/default/gearman-job-server
+
+3. Restart gearman
+
+::
+
+    $ sudo service gearman-job-server restart
+
+
+Bring up services
+=================
+
+1. Start the Pool Manager
+
+::
+
+    $ libra-pool-mgm -c /etc/libra.cfg
+
+2. Start Admin API & API services
+
+::
+
+    $ libra-admin-api -c /etc/libra.cfg
+    $ libra-api -c /etc/libra.cfg
+
+
+Creating a Worker Image
+=======================
+
+.. note::
+
+    In this setup we'll be using OpenStack as the underlying provider for our Libra Worker nodes to run HAProxy on.
+
+1. Boot a server using Nova
+
+.. note::
+
+    You should at least open (for now at least) port 22 for ssh.
+
+    --nic argument is only needed if you have multiple networks.
+    --security-groups is not needed at the time if you have 22 in default
+
+::
+
+    $ nova boot --flavor <flavour id or name> --image <image id of ubuntu precise> --key-name default --nic net-id=<network id> --security-groups=<your security groups> worker
+
+2. Create a floating ip
+
+::
+
+    $ neutron floatingip-create <external network name>
+
+3. Assign a floating ip to the instance
+
+.. note::
+
+    You can view all the ports by issuing `neutron port-list`.
+
+::
+
+    $ neutron floatingip-associate <floating ip id> <port id>
+
+4. Login to the instance
+
+::
+
+    $ ssh ubuntu@<ip>
+
+5. Do steps in 'Common steps'
+
+6. Install HAProxy
+
+::
+
+    $ apt-get install -qy haproxy socat
+
+
+7. Install python-gearman
+
+.. note::
+
+    This is a custom version with patches commited upstream but not release yet.
+
+   sudo pip install  https://launchpad.net/~libra-core/+archive/ppa/+files/gearman_2.0.2.git2.orig.tar.gz
+
+8. Install dependencies using pip
+
+::
+
+    $ sudo pip install -r requirements.txt -r test-requirements.txt
+
+9. Install Libra in development mode
+
+::
+
+    $ sudo python setup.py develop
+
+10. Install a Upstart job
+
+::
+
+    $ sudo wget https://raw.github.com/pcrews/lbaas-salt/master/lbaas-haproxy-base/libra_worker.conf -O /etc/init/libra_worker.conf
+
+11. Make a snapshot of the worker image
+
+::
+
+    $ nova image-create worker libra-worker
+
+12. At the libra-poo-mgm node change the 'nova_image' setting to the value of your newly created snapshot
+
+.. note::
+
+    To get the ID of the snapshot do
+    glance image-show libra-worker | grep -w id | cut -d '|' -f3
+
+::
+
+    $ sudo vi /etc/libra.cfg
+
+13. Restart libra-pool-mgm
+
+::
+
+    $ killall -9 libra_pool_mgm
+    $ libra_pool_mgm -c /etc/libra.cfg
+
+Verifying that it works
+=======================
+
+If you have done all correctly you should be able to do something like the
+below command on the node that has the :ref:`libra-pool-mgm`
+
+::
+
+    $ tail -f /var/log/libra/libra_mgm.log

doc/installation/ppa.rst

@@ -0,0 +1,26 @@
+.. _ppa:
+
+=========
+Libra PPA
+=========
+
+Currently we require a PPA that is provided by the HPCS LBaaS / Libra team in order
+to get the right versions of the dependencies. So we'll need to setup a PPA.
+
+To add it to your Ubuntu node follow the instructions below.
+
+
+Adding the PPA
+==============
+
+1. Install a utility package
+
+::
+
+    $ sudo apt-get install python-software-properties
+
+2. Add the PPA
+
+::
+
+    $ sudo apt-add-repository ppa:libra-core/ppa

doc/pool_mgm/index.rst

@@ -1,4 +1,4 @@
-.. _libra-pool-mgr:
+.. _libra-pool-mgm:
 
 Libra Node Pool Manager
 =======================