= Bitten Installation =
[[PageOutline(2)]]

{{{
#!div class=important

'''Note:''' This page is outdated and no longer maintained - see the [wiki:Documentation/index.html official documentation] that includes an updated [wiki:Documentation/install.html installation guide].
}}}

Bitten is a simple distributed continuous integration system that not only coordinates builds across multiple machines, but also collects software metrics generated by builds, to enable feedback and reporting about the progress of a software project.

The Bitten software consists of three separate parts:
 * The build slave, which executes build on behalf of a local or remote build master
 * The build master, which orchestrate builds for a project across all connected slaves, and stores the build status and results to the database
 * The web interface, which is implemented as an add-on to [http://trac.edgewall.com/ Trac] allows to manage builds and view build results.

Both the build master and the web interface depend on Trac 0.11, and need to be installed on the same machine, together with the [http://subversion.apache.org/ Subversion] repository. The build slave only requires [http://www.python.org/ Python] (>= 2.4) and [http://peak.telecommunity.com/DevCenter/setuptools setuptools], as well as the tools required by the build process itself. A build slave may be run on any machine that can connect to the server running the Bitten build master.


== Installation ==

Bitten is written in Python, so make sure that you have Python installed. You'll need Python 2.4 or later. Also, make sure that [http://peak.telecommunity.com/DevCenter/setuptools setuptools] (version 0.6a2 or later) is installed.

If that's taken care of, you just need to download and unpack the [http://bitten.edgewall.org/wiki/Download 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 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:
{{{
  $ 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 also need to install [http://trac.edgewall.com/ Trac] 0.11 and its dependencies. Please refer to the [http://projects.edgewall.com/trac/wiki/TracInstall Trac documentation] for information on how it is installed.

== Build Master Configuration ==

Once 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`:
{{{
  [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
}}}

If you've setup your web server to serve static resources independently of Trac (these are images and styles usually accessed by with /chrome/* style URLs), you may need to reexport them to include Bitten files:
{{{
  $ trac-admin . deploy /dir/with/apache/served/chrome
}}}

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_VIEW
  $ trac-admin /path/to/projenv permission add [yourname] BUILD_ADMIN
}}}

You should now see an additional tab labelled "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. If you've set up permissions correctly as described previously, you should see a button for adding new build configurations. Click that button 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" the build configuration.


== Running the Build Master ==

At this point, you're ready to start the Bitten build master. The installation of Bitten should have put a `bitten-master` 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 find out about the options and arguments of the build master, execute it with the `--help` option as follows:
{{{
  $ bitten-master --help
}}}

Most commonly, you'll want to specify the log level and log file, as well as the path to the Trac environment:
{{{
  $ bitten-master --verbose --log=/var/log/bittend /var/trac/myproject
}}}

If you have a firewall between the build master and the build slaves, make sure that there is an open TCP port (7633 by default).

== 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. Just as with the build master, you should find the build slave executable on your path after the installation. The executable file is called `bitten-slave`.

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 master project called myproject, installed on trac.example.org, you'd run:
{{{
  $ bitten-slave https://trac.example.org/myproject/builds
}}}