.. -*- mode: rst; encoding: utf-8 -*-

============
Installation
============

.. contents:: Contents
   :depth: 2
.. sectnum::


Prerequisites
=============

Bitten is written in Python, so make sure that you have Python installed.
You'll need Python 2.3 or later. Also, make sure that setuptools_, version 0.6a2
or later, is installed.

.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools

If that's taken care of, you just need to download and unpack the Bitten
distribution, and execute the command::

  $ python setup.py install

from the top of the directory where you unpacked (or checked out) the Bitten
code. Note that you may need administrator/root privileges for this step, as
it will by default attempt to install Bitten to the Python site-packages
directory on your system.

It's also a good idea to run the unit tests at this point, to make sure that
the code works as expected on your platform (please note that Trac_ needs to
be installed for the tests to run; see below)::

  $ python setup.py test


What's left to do now depends on whether you want to use the build master and
web interface, or just the build slave. In the latter case, you're already
done. You might need to install software that the build of your project
requires, but the Bitten build slave itself doesn't require anything extra.

For the build master and web interface, you'll need to install Trac_ 0.10 or
later and the TracWebAdmin_ plugin. Please refer to the Trac documentation for
information on how it is installed.

.. _trac: http://trac.edgewall.org/
.. _tracwebadmin: http://trac.edgewall.org/wiki/WebAdmin


Build Master Configuration
==========================

Once both Bitten and Trac are installed and working, you'll have to introduce
Bitten to your Trac project environment. If you don't have a  Trac project
set up yet, you'll need to do so in order to use Bitten.

If you already have a Trac project environment, the Bitten plugin needs to be
explicitly enabled in the Trac configuration. This is done by adding it to the
``[components]`` section in ``/path/to/projenv/conf/trac.ini``:

.. code-block:: ini

  [components]
  bitten.* = enabled

The Trac web interface should now inform you with an error message that the
environment needs to be upgraded. To do this, run::

  $ trac-admin /path/to/projenv upgrade

This will create the database tables and directories that Bitten requires.
You probably also want to grant permissions to someone (such as yourself)
to manage build configurations, and allow anonymous users to view the
status and results of builds::

  $ trac-admin /path/to/projenv permission add anonymous BUILD_EXEC
  $ trac-admin /path/to/projenv permission add anonymous BUILD_VIEW
  $ trac-admin /path/to/projenv permission add [yourname] BUILD_ADMIN

You should now see an additional tab labeled "Build Status" in the Trac
navigation bar. This link will take you to the list of build configurations,
which at this point is of course empty.

To add build configurations, you need to have the TracWebAdmin_ plugin
installed.

.. warning:: The TracWebAdmin needs to be installed even if you're using Trac
             0.11 or later, which basically provides a builtin web
             administration interface. Make sure that you disable the plugin in
             that case, though (``webadmin.* = disabled``). While somewhat
             counterintuitive, this process allows the Bitten administration UI
             to neatly integrate into the new web administration interface added
             in Trac 0.11.

If both TracWebAdmin_ and Bitten are installed, and you are logged in as a user
with the required permissions, you should see additional administration pages
inside the “Admin” area, under a group named “Builds”. These pages allow you to
set options of the build master, and manage build configurations.

Add a new build configuration and fill out the form. Also, add at least one
target platform after saving the configuration. Last but not least, you'll have
to "activate" your new build configuration.


Running the Build Slave
=======================

The build slave can be run on any machine that can connect to the machine
on which the build master is running. The installation of Bitten should have put
a `bitten-slave` executable on your path. If the script is not on your path,
look for it in the `bin` or `scripts` subdirectory of your Python installation.

To get a list of options for the build slave, execute it with the `--help`
option::

  $ bitten-slave --help

To run the build slave against a Bitten-enabled Trac site installed at 
http://myproject.example.org/trac, you'd run::

  $ bitten-slave http://myproject.example.org/trac/builds