Requirements

Loggerhead depends on a number of other Python packages for the various Web technologies that it builds on. Some of these must be installed to use loggerhead, although some of them are optional. From the loggerhead README file, these are

1. SimpleTAL for templating. On Ubuntu, sudo apt-get install python-simpletal or download from http://www.owlfish.com/software/simpleTAL/download.html
2. simplejson for producing JSON data. On Ubuntu, sudo apt-get install python-simplejson or use easy_install simplejson.
3. Paste for the server. (You need version 1.2 or newer of Paste.) On Ubuntu, sudo apt-get install python-paste or use easy_install Paste
4. Paste Deploy (optional, needed when proxying through Apache) On Ubuntu, sudo apt-get install python-pastedeploy or use easy_install PasteDeploy
5. flup (optional, needed to use FastCGI, SCGI or AJP) On Ubuntu, sudo apt-get install python-flup or use easy_install flup

Although directions for installing these on Ubuntu Linux are given, most other Linux distributions should package these dependencies, making installation easy. For Windows and Mac OS X, they should all be easy_install-able or at worst installable from the Python sources.

Built-in Web Server

Loggerhead has a built-in web server and when started with the serve-branches command, that web server is started on a default port listening on the localhost. If port 8080 (the default) is accessible on www.example.com, then running

$ serve-branches --host=www.example.com --port=8080 /srv/bzr

will list all of the available branches under that directory on http://www.example.com:8080/, so that the ProjectX trunk could be browsed at http://www.example.com:8080/projectx/trunk. Note that loggerhead provides HTTP access to the underlying Bazaar branches (similar to that described in Smart server over HTTP(S)), so this command should be run as a user without write privileges in /srv/bzr. By default, loggerhead only listens on the localhost, not any external ports, unless specified as above.

Behind a Proxy

A more common and more safe way to run loggerhead is behind another web server which will proxy certain requests to the loggerhead server on the localhost. To do this, you need to have PasteDeploy installed (see Requirements). Assuming that your server has Apache running, you need to add configuration such as this to set up the proxy

<Location "/loggerhead/">
    ProxyPass http://127.0.0.1:8080/
    ProxyPassReverse http://127.0.0.1:8080/
</Location>

If your proxy runs at some path within the server, then the serve-branches command must be started with the --prefix option. For this example, we could start loggerhead with the command

$ serve-branches --prefix=/loggerhead /srv/bzr

This would allow the trunk branch of ProjectX to be browsed at http://www.example.com/loggerhead/projectx/trunk.

Loggerhead comes with a script allowing it to run as a service on init.d based Linux systems. Contributions to do a similar thing on Windows servers would be welcomed at http://launchpad.net/loggerhead.