~zyga/lava-dashboard-tool/new-ui

LAVA Deployment Tool
====================

LAVA Deployment Tool is meant to assist you setting up LAVA on your machine.
The tool is suitable for both personal and more "production" installations that
are expected to perform adequately with more concurrent users. This tool is
not, however, designed for multi-machine installation, including cloud
deployment. For that it is likely we will turn to Juju
(https://juju.ubuntu.com/)

Quickstart
^^^^^^^^^^
For the impatient, or those just looking for a cheat sheet but know what they
are doing otherwise, here are the basic set of commands to get an instance
up and running based on the requirements-mini file provided as an example, 
which only installs lava-server.

 $ ./lava-deployment-tool setup
 $ ./lava-deployment-tool bundle requirements-mini.txt
 $ ./lava-deployment-tool install testinstance lava.pybundle
 $ sudo start lava-instance LAVA_INSTANCE=testinstance

Assuming everything went well, you should be able to point a web browser
at the system you did this on and see the lava-server default page.


Software Requirements
^^^^^^^^^^^^^^^^^^^^^

This tool should work on Ubuntu versions starting with 10.10 release
(Maverick). If you'd like to help us with other distributions feel free to
contact us at validation (at) linaro (dot) org.

Hardware Requirements
^^^^^^^^^^^^^^^^^^^^^

A small LAVA instance can be deployed on any modest hardware. We recommend at
least one 1GB of RAM for runtime activity (this is shared, on a single host,
among the database server, the application server and the web server). For
storage please reserve about 20GB for application data, especially if you wish
to mirror current public LAVA instance used by Linaro. LAVA uses append-only
models so the storage requirements will grow at about several GB a year.

Before installing
^^^^^^^^^^^^^^^^^

Before you can create your first LAVA instance (standalone, independent LAVA
installation) you must install some shared infrastructure on your machine.
Currently this is the Apache 2 web server, PostgreSQL database server, RabbitMQ
messaging server, and Python (and a few python programs and libraries). Because
this installation method is not using pre-built packages you will also need
development headers and a working compiler to build some of the native (C)
extensions for python.

This step is largely automated. To perform it run this command:

$ ./lava-deployment-tool setup

This step also prepares file-system places for LAVA. In particular it creates
/srv/lava/ where all LAVA instances are later stored.

Creating LAVA instance
^^^^^^^^^^^^^^^^^^^^^^

You can create multiple LAVA instances on a single machine. Being able to do
so is very valuable for testing and developing LAVA itself. Before installing
you must first create a bundle of sources you wish to install.  This simply 
downloads all the things you intend to install into a single, local archive
so that installation or updating is not impacted by any problems getting the
sources later.  This also enables offline installs, or installs behind a
restrictive firewall by allowing you to download the bundle in advance.
To create the bundle, run:

$ ./lava-deployment-tool URL_to_requirements [bundle_file_name]
If you do not specify the bundle_file_name, it will use the name 'lava.pybundle'

To create a new instance run this command:

$ ./lava-deployment-tool install NAME BUNDLE

This will create a fresh instance called NAME, the instance will be composed of
the software specified in the requirements file that was used to build the
bundle and associated dependencies.

The script produces verbose output, at the end it should say that everything
went fine.

Backing Up LAVA instance
^^^^^^^^^^^^^^^^^^^^^^^^

LAVA instances store persistent data in two locations:

 * On the filesystem, in the directory
   /srv/lava/$LAVA_INSTANCE/var/lib/lava-server/media
 * In a PostgreSQL database in the default cluster named $LAVA_INSTANCE

Backing up those two items is sufficient to preserve the entire system
state.  You can do this by running:

$ lava-deployment-tool backup $LAVA_INSTANCE

which will create a backup with an ID based on the current date and
time in a directory named
"/srv/lava/backups/$LAVA_INSTANCE/$SNAPSHOT_ID/".  You can make
/srv/lava/backups a symlink to a more appropriate location if you
want.

Generally before backing up you should make sure that LAVA instance is
turned off. This depends on how your instance is started. If you were
using upstart the following shell command should turn LAVA off:

$ sudo service lava stop

If you take a backup while running, you will need to do some manual
cleanup when you restore from it.

Restoring from backup
^^^^^^^^^^^^^^^^^^^^^

Running the command

$ lava-deployment-tool restore $LAVA_INSTANCE $SNAPSHOT_ID

will restore the given snapshot of the named instance.  This will
first erase the database and media files of the named instance, so be
careful what you type!

You can restore an instance from a backup taken from a distinct
instance with a command like:

$ lava-deployment-tool restore $TARGET_INSTANCE $SOURCE_INSTANCE/$SNAPSHOT_ID

Currently to restore from a backup taken on a different machine, you
have to put it under /srv/lava/backups, then run an appropriate
"lava-deployment-tool restore" command (we will hopefully make this
more natural soon).

You cannot restore to an instance while it is running.

Updating LAVA instance
^^^^^^^^^^^^^^^^^^^^^^

LAVA is released periodically. Currently this is once a month but the release
cycle becomes more and more fluid and eventually we'd like to release multiple
tiny changes every day.

Once you installed some LAVA components you can upgrade your installation to a
more recent release using this deployment tool. There are some important
upgrade considerations:

1) Upgrades may alter the database or persistent media files. It is wise to
perform a full system backup before each upgrade. While we don't anticipate
catastrophic failures it's better to be safe than sorry. Refer to the previous
chapter for details.

2) Some database schema changes take a lot of time to finish. We try to
minimize such changes but as you can install any third-party LAVA extensions we
cannot predict the overall downtime in such case. For official Linaro releases
please refer to our monthly release notes that are available at
http://lava.readthedocs.org/

3) Upgrades may introduce additional dependencies, which will be installed
automatically. Periodically we make use of additional third party open source
libraries. Those libraries will be installed for a single LAVA instance
_only_. Your system libraries are not affected by this step. 

4) Upgrades require network access. If you are behind a firewall or a
corporate http proxy you may experience failures. Please note that the
upgrade process does not install components without first downloading all of
the required pieces so in case of a network failure your current installation
should not be affected. While typically only HTTP and HTTPS protocols are
being used at times you may see attempts to connect to native protocols used
by git, bazaar or mercurial.

5) Upgrading process rebuilds the collection of static assets served by
Apache. During that moment you may encounter a very brief failure to resolve
some of the static assets (typically images, cascading style sheets and
javascript libraries)

Prior to upgrading and instance, you will need to build a new bundle based
on your new requirements file:

$ ./lava-deployment-tool bundle URL-to-requirements [bundle_file_name]

To upgrade an existing instance run the following command:

$ ./lava-deployment-tool upgrade NAME BUNDLE

Again the NAME and URL-to-requirements have the same meaning as in the
install command mentioned in preceding chapter.

Anatomy of a LAVA instance
^^^^^^^^^^^^^^^^^^^^^^^^^^

An instance is composed of several parts:

 - A new system user account called $LAVA_INSTANCE
 - A directory tree similar to standard unix filesystem rooted
   in $LAVA_PREFIX/$LAVA_INSTANCE/
 - A postgres user and database in the default cluster, both named
   $LAVA_INSTANCE

A note on Postgres versions
^^^^^^^^^^^^^^^^^^^^^^^^^^^

lava-deployment-tool creates its databases in the default postgres
cluster (on Ubuntu this is the 'main' cluster of whichever version of
postgres was installed first).  Using a different version/cluster and
moving between versions is not technically difficult but not currently
supported.

Contact and bug reports
^^^^^^^^^^^^^^^^^^^^^^^

Please report bugs using
https://bugs.launchpad.net/lava-deployment-tool/+filebug

Feel free to contact us at validation (at) linaro (dot) org.