cmlenz@412: .. -*- mode: rst; encoding: utf-8 -*-
cmlenz@412: 
cmlenz@412: ============
cmlenz@412: Installation
cmlenz@412: ============
cmlenz@412: 
cmlenz@412: .. contents:: Contents
cmlenz@412:    :depth: 2
cmlenz@412: .. sectnum::
cmlenz@412: 
cmlenz@412: 
cmlenz@412: Prerequisites
cmlenz@412: =============
cmlenz@412: 
cmlenz@412: Bitten is written in Python, so make sure that you have Python installed.
cmlenz@412: You'll need Python 2.3 or later. Also, make sure that setuptools_, version 0.6a2
cmlenz@412: or later, is installed.
cmlenz@412: 
cmlenz@412: .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
cmlenz@412: 
cmlenz@412: If that's taken care of, you just need to download and unpack the Bitten
cmlenz@412: distribution, and execute the command::
cmlenz@412: 
cmlenz@412:   $ python setup.py install
cmlenz@412: 
cmlenz@412: from the top of the directory where you unpacked (or checked out) the Bitten
cmlenz@412: code. Note that you may need administrator/root privileges for this step, as
cmlenz@412: it will by default attempt to install Bitten to the Python site-packages
cmlenz@412: directory on your system.
cmlenz@412: 
cmlenz@412: It's also a good idea to run the unit tests at this point, to make sure that
dfraser@522: the code works as expected on your platform (please note that Trac_ needs to
dfraser@522: be installed for the tests to run; see below)::
cmlenz@412: 
cmlenz@412:   $ python setup.py test
cmlenz@412: 
cmlenz@412: 
cmlenz@412: What's left to do now depends on whether you want to use the build master and
cmlenz@412: web interface, or just the build slave. In the latter case, you're already
cmlenz@412: done. You might need to install software that the build of your project
cmlenz@412: requires, but the Bitten build slave itself doesn't require anything extra.
cmlenz@412: 
cmlenz@436: For the build master and web interface, you'll need to install Trac_ 0.10 or
cmlenz@436: later and the TracWebAdmin_ plugin. Please refer to the Trac documentation for
cmlenz@436: information on how it is installed.
cmlenz@436: 
cmlenz@436: .. _trac: http://trac.edgewall.org/
cmlenz@436: .. _tracwebadmin: http://trac.edgewall.org/wiki/WebAdmin
cmlenz@412: 
cmlenz@412: 
cmlenz@412: Build Master Configuration
cmlenz@412: ==========================
cmlenz@412: 
cmlenz@412: Once both Bitten and Trac are installed and working, you'll have to introduce
cmlenz@412: Bitten to your Trac project environment. If you don't have a  Trac project
cmlenz@412: set up yet, you'll need to do so in order to use Bitten.
cmlenz@412: 
cmlenz@412: If you already have a Trac project environment, the Bitten plugin needs to be
cmlenz@412: explicitly enabled in the Trac configuration. This is done by adding it to the
cmlenz@436: ``[components]`` section in ``/path/to/projenv/conf/trac.ini``:
cmlenz@412: 
cmlenz@412: .. code-block:: ini
cmlenz@412: 
cmlenz@412:   [components]
cmlenz@412:   bitten.* = enabled
cmlenz@412: 
cmlenz@412: The Trac web interface should now inform you with an error message that the
cmlenz@412: environment needs to be upgraded. To do this, run::
cmlenz@412: 
cmlenz@412:   $ trac-admin /path/to/projenv upgrade
cmlenz@412: 
cmlenz@412: This will create the database tables and directories that Bitten requires.
cmlenz@412: You probably also want to grant permissions to someone (such as yourself)
cmlenz@412: to manage build configurations, and allow anonymous users to view the
cmlenz@412: status and results of builds::
cmlenz@412: 
cmlenz@412:   $ trac-admin /path/to/projenv permission add anonymous BUILD_EXEC
cmlenz@412:   $ trac-admin /path/to/projenv permission add anonymous BUILD_VIEW
cmlenz@412:   $ trac-admin /path/to/projenv permission add [yourname] BUILD_ADMIN
cmlenz@412: 
cmlenz@412: You should now see an additional tab labeled "Build Status" in the Trac
cmlenz@412: navigation bar. This link will take you to the list of build configurations,
cmlenz@436: which at this point is of course empty.
cmlenz@436: 
cmlenz@436: To add build configurations, you need to have the TracWebAdmin_ plugin
cmlenz@436: installed.
cmlenz@436: 
cmlenz@436: .. warning:: The TracWebAdmin needs to be installed even if you're using Trac
cmlenz@436:              0.11 or later, which basically provides a builtin web
cmlenz@436:              administration interface. Make sure that you disable the plugin in
cmlenz@436:              that case, though (``webadmin.* = disabled``). While somewhat
cmlenz@436:              counterintuitive, this process allows the Bitten administration UI
cmlenz@436:              to neatly integrate into the new web administration interface added
cmlenz@436:              in Trac 0.11.
cmlenz@436: 
cmlenz@436: If both TracWebAdmin_ and Bitten are installed, and you are logged in as a user
cmlenz@436: with the required permissions, you should see additional administration pages
cmlenz@436: inside the “Admin” area, under a group named “Builds”. These pages allow you to
cmlenz@436: set options of the build master, and manage build configurations.
cmlenz@436: 
cmlenz@436: Add a new build configuration and fill out the form. Also, add at least one
cmlenz@436: target platform after saving the configuration. Last but not least, you'll have
cmlenz@436: to "activate" your new build configuration.
cmlenz@412: 
cmlenz@412: 
cmlenz@412: Running the Build Slave
cmlenz@412: =======================
cmlenz@412: 
cmlenz@412: The build slave can be run on any machine that can connect to the machine
cmlenz@412: on which the build master is running. The installation of Bitten should have put
cmlenz@412: a `bitten-slave` executable on your path. If the script is not on your path,
cmlenz@412: look for it in the `bin` or `scripts` subdirectory of your Python installation.
cmlenz@412: 
cmlenz@412: To get a list of options for the build slave, execute it with the `--help`
cmlenz@412: option::
cmlenz@412: 
cmlenz@412:   $ bitten-slave --help
cmlenz@412: 
cmlenz@412: To run the build slave against a Bitten-enabled Trac site installed at 
cmlenz@412: http://myproject.example.org/trac, you'd run::
cmlenz@412: 
cmlenz@412:   $ bitten-slave http://myproject.example.org/trac/builds