README.md.bak

# Ursula

Ursula provides a series of Ansible playbooks for installing, managing and
maintaining OpenStack powered clouds.

Ursula was originally created by a team at [Blue Box](https://www.bluebox.net) and is 
released under the MIT License (MIT).

# Installation

## System Dependencies

The following system packages ( or their equivalents for your OS ) are
required to run `ursula`: 

* python-pip 
* python-dev 
* libxml2-dev 
* libxslt-dev 
* libffi-dev

## Python Environment

We recommend using [virtualenv](http://virtualenv.readthedocs.org/en/latest/) or
[virtualenvwrapper](https://virtualenvwrapper.readthedocs.org/en/latest/) 
to isolate your Python environment. 

If you're new to python the following will install `virtualenvwrapper` and set
up a `virtualenv` for ursula.

```bash
$ pip install virtualenvwrapper
$ mkvirtualenv ursula
```

From now on to work with ursula you can run `$ workon ursula` to 
enter the `virtualenv`

## Install ursula and dependencies:

now that your python environment is ready you can clone ursula and install
it's prerequisites:

```bash
$ cd ~/development
$ git clone git@github.com:blueboxgroup/ursula.git
$ cd ursula
$ pip install -r requirements.txt
```

This will have installed `ursula-cli`, the various openstack clients, and our
patched fork of `Ansible`.

# ursula-cli

Ursula was designed by [Blue Box](https://www.bluebox.net) to manage a large
number of OpenStack deployments. In order to do this efficiently we've made
some changes to how `ansible` works. As part of these changes we have a
wrapper tool called `ursula-cli` which was installed during the 
`pip install -r requirements.txt` above.

Make sure `ursula-cli` is installed in your environment:

```
ursula -h
usage: ursula [-h] [--ursula-forward] [--ursula-test] [--ursula-debug]
              environment playbook

A CLI wrapper for ansible
...
...
```

There are two mandatory fields required by `ursula-cli`.  The first is 
`environment` which will require some further explanation.  
The second is `playbook` which will almost always be `site.yml`.

## openstack-envs

One of the modifications that we have made to `Ansible` is the ability to have
a seperate path that includes all of the configuration options for your
OpenStack deployment[s].   An example of this can be found in `/envs/example`

If you look in the `/envs/example` path you'll see a `defaults.yml` file and a
series of directories each representing a different OpenStack deployment.

We then utilize the standard `Ansible` features by having `group_vars`, 
`host_vars`, and a `hosts` file.

There are also some `vagrant.yml` files scattered around.  These are helper
files to make using `Vagrant` even easier with `ursula` to test your
environments in VMs.

### allinone

The simplest example deployment is `allinone` which is a single server
deployment that acts as both a `controller` and a `compute` node.

Whether or not you're using `Vagrant` If you look in the 
`envs/example/allinone/vagrant.yml` file it will give you some hints on what
your server should look like.  If you do not wish to use `Vagrant` then you
should install Ubuntu 12.04 on a server and configure its networking as
described in the `vagrant.yml` file.

Next look in the `hosts` file.  It's very simple in this case due to the fact
we have only a single server.  This file combined with the `site.yml` playbook
tells Ansible what roles to apply to which servers.

Finally we have the `group_vars/all.yml` file.  This contains values that will
override the `defaults.yml` in the parent directory.  For example we're
disabling Percona replication by setting `percona.replication: False`.

## Performing a deployment:

For the sake of simplicity for your first install I recommend using `Vagrant`
rather than `Manual`

### Manually

If you're not running `Vagrant` and have installed ubuntu onto a server and
configured the networking then we need to tell our system how to talk to this
new server.  The easiest way is via an entry in your ssh config file in 
`~/.ssh/config`.

```
Host allinone
  HostName 172.16.0.100
  User ubuntu
  IdentityFile ~/.ssh/private_key
```

```bash
$ ursula envs/example/allinone site.yml
```

### Vagrant

If you're running `Vagrant` we have a wrapper script that stands up the
appropriate vagrant environment, saves it as an ssh config and then calls
`ursula` for you.

To deploy your `allinone` environment via `Vagrant` simply run:

```bash
$ bin/run_vagrant up allinone
```

Note: The default OS for ursula is Ubuntu Trusty, if you want Precise set
the env var `URSULA_BOX_NAME` to the name of your precise vagrant
box before running vagrant.

# More Docs

See the [/doc](https://github.com/blueboxgroup/ursula/tree/master/doc) directory of this repo.