eating cucumbers without permission...

Installing Roundup 1.4.6 at Dreamhost stretched from the “15-30 minutes” specified in the installation docs to something more like four hours. This is a collection of notes for next time.

Dramatis Personae

Roundup is the software. It’s billed as “a simple-to-use and -install issue-tracking system”, but it’s so configurable that it’s probably better described as a lightweight tracker-oriented framework.

The Roundup installatation includes the Roundup module — i.e., what you get when you import roundup — and a set of administration scripts: roundup-admin, roundup-server etc.

You can use the roundup-admin script to create a tracker. If Roundup is a framework, the tracker is the application. It includes a data schema, page templates, extensions, custom behaviours and so on.

To access the tracker you will need to set up the web interface.

1. Installation

If you get the source distribution, the instructions suggest that you install it. Don’t.

Which is to say, the docs assume that you are a server administrator attempting to add the Roundup module and associated scripts into your Python installation directory. If you run this:

`python setup.py install --prefix test_directory`

The result is:

• test_directory/Lib/site-packages/roundup/ — Roundup module
• test_directory/Scripts/ — platform-specific administration scripts
• test_directory/share/roundup/templates/ — included templates
• test_directory/share/roundup/cgi-bin/ — included web interface
• test_directory/share/locale/ — translation files

i.e., files that slot neatly into a Python install. Because I have not installed a custom version and obviously can’t touch the server-wide installation, this structure is not ideal.

2. Be Careful About Changing The Directory Structure

I want the Roundup module in my directory for Python libraries, /home/me/pylib. I don’t care about locales and the scripts are just thin wrappers around Python files in roundup/scripts.

It’s the templates that are the problem. The comment on the listTemplates function in roundup/admin.py reveals the 5-step process Roundup uses to find them:

Look in the following places, where the later rules take precedence:

1. <roundup.admin.__file__>/../../share/roundup/templates/*
   this is where they will be if we installed an egg via easy_install
2. <prefix>/share/roundup/templates/*
   this should be the standard place to find them when Roundup is installed
3. <roundup.admin.__file__>/../templates/*
   this will be used if Roundup’s run in the distro (aka. source) directory
4. <current working dir>/*
   this is for when someone unpacks a 3rd-party template
5. <current working dir>
   this is for someone who “cd”s to the 3rd-party template dir

Either throw the templates directory into /home/me/pylib too or only ever run the roundup-admin script from a template directory. Or, if you don’t already have a directory for libraries, just run it from the source distribution.

3. Create a Tracker

Run roundup-admin if you’ve installed Roundup and the script is on your PATH, otherwise python roundup_admin.py.

Type install and follow the prompts:

Enter tracker home: /home/me/tracker/
Templates: classic, minimal
Select template [classic]: classic
Back ends: anydbm, mysql, sqlite
Select backend [anydbm]: mysql

If the template or backend files can’t be found, it won’t be possible to select them, so exit and fix the problem.

You’ll have to come back to roundup-admin later, but now it’s time to configure the tracker.

4. Configure Your Tracker

Head to /home/me/tracker/ and edit config.ini. Search for “NO DEFAULT” to find the items that need to be set. The tracker won’t run at all if they’re not.

In the Dreamhost context, consider a subdomain — http://tracker.example.com/ — because it will make deployment much easier.

Return to roundup-admin and initialise the tracker to set up the default user accounts and roles.

5. Creating The Web Interface

I spent several hours failing to track down mysterious bugs apparently caused by some combination of my tracker settings and the bundled CGI interface. Try using the WSGI interface instead:

#!/usr/bin/env python2.4

# Enable HTML tracebacks
import cgitb
cgitb.enable()

# obtain the WSGI request dispatcher
from roundup.cgi.wsgi_handler import RequestDispatcher
tracker_home = '/home/me/tracker/'
app = RequestDispatcher(tracker_home)

from wsgiref.handlers import CGIHandler
CGIHandler().run(app)

Note that wsgiref isn’t included in Python 2.4. Dreamhost isn’t providing 2.5 yet, so just download the package and put it somewhere handy.

6. Deploying With Passenger

You can use Phusion Passenger to deply WSGI applications; the wiki has more details. Just set it up in the panel and modify the web interface a little:

#!/usr/bin/env python2.4

import sys, cgitb

# Enable HTML tracebacks
cgitb.enable()

# Even if you've got your paths set up to find
# your python libraries automatically, Passenger's
# interpreter won't.
sys.path.append("/home/me/pylib")

from roundup.cgi.wsgi_handler import RequestDispatcher

# The WSGI app has to be called "application"
application = RequestDispatcher("/home/me/tracker/")

# That's it.

Save it as passenger_wsgi.py and you’re good to go.