The best way to install Loggerhead is by using your operating system's package manager. Look for a package named loggerhead. In case that is not an option for you, we explain how to install Loggerhead by using pip and virtualenv.

When installing web tools written in Python, it is always recommended to use virtualenv in order to isolate the tool's Python dependencies from the rest of the Python packages in the system. This is a good way to give Loggerhead a try, and since all of its files and dependencies will be contained within a single directory, it is also easy to clean up after testing.

First, let's create the “virtual environment" where we will install Loggerhead:

$ virtualenv --distribute loggerhead
New python executable in loggerhead/bin/python
Installing distribute..........................................................................................................................................................................................................done.
Installing pip................done.

A directory named loggerhead was just created, where all Python libraries and scripts that we are going to install will be stored, such as Loggerhead and its dependencies. This works by setting up environment variables such as PATH and PYTHONPATH appropriately, which we can do easily by sourcing the activation script of the virtual environment:

$ . loggerhead/bin/activate
(loggerhead)$

When a virtual environment is activated, the shell prompt is changed to indicate the name of the virtual environment; in this case the prompt became (loggerhead)$ instead of $. This simply means that now environment variables such as PATH and PYTHONPATH are configured in a way that anything we install using pip or python setup.py install, they will be installed within the directory of the virtual environment.

Next, let's install Loggerhead and its dependencies using pip:

(loggerhead)$ pip install paste bzr simplejson
# ... (skip)
(loggerhead)$ pip install loggerhead
# ... (skip)

There is one more dependency, which is not available via pip, called SimpleTAL, a template language. We need to install this in the old fashioned way, from a tarball. You can get the latest version of the Python 2.x series from the following URL:

http://www.owlfish.com/software/simpleTAL/py2compatible/download.html

Unpack and install the python module with:

(loggerhead)$ tar zxf SimpleTAL-4.3.tar.gz
(loggerhead)$ cd SimpleTAL-4.3
(loggerhead)$ python setup.py install
# ... (skip)

That's it, now we are ready to run Loggerhead!

An easy way to test Loggerhead is to run it by using its built-in web server:

(loggerhead)$ serve-branches file:///srv/bzr

The single parameter in this example is the path to a directory, typically the parent directory or the shared repository that contains several Bazaar branches.

By default, the web server will listen on port 8080 of localhost. Thus if you visit http://localhost:8080/, you should see the contents of the specified root directory and browse its contents:

In this example, there is a mix of Bazaar branches and regular directories, which can be distinguished by their icons, and the extra information by Loggerhead such as the latest revision number and timestamp.

When inside a branch, the view is much like on Launchpad:

For example, we can download this branch with the following command:

$ bzr branch http://localhost:8080/bzr/webtools/highlighter

There is a lot more to Loggerhead than we can cover here. For a brief introduction of other configuration options, such as running Loggerhead behind an Apache web server, see the documentation in the Bazaar admin guide:

http://doc.bazaar.canonical.com/beta/en/admin-guide/code-browsing.html#loggerhead

To see the complete list of command-line options of serve-branches, use the -h or --help flags.