Roundup

An Issue-Tracking System for Knowledge Workers

Contents

Installation

Prerequisites

Either:
Python 2.0 with pydoc installed. See http://www.lfw.org/ for pydoc.
or
Python 2.1 or later
Download the latest version from http://www.python.org/.

Getting Roundup

Download the latest version from http://roundup.sf.net/.

Installing Roundup

  1. Run:
    python setup.py install
  2. If you would prefer the scripts installed in somewhere other than /usr/local/bin, add "--install-scripts=<dir>" to the command:
    python setup.py install --install-scripts=<dir>
  3. The command:
    python setup.py install --help
    gives all the options available for installation.

Getting Started

The following instructions assume that you have installed roundup. If you haven't, you may still proceed - just preface all commands with "./" ie. "./roundup-admin init".

The Instance

We'll be referring to the term "instance" a lot from now on. An instance is a directory in your filesystem that is where all the information about a live issue tracker database is stored. The data that is entered as issues, the users who access the database and the definition of the database itself all reside there:
  1. Hyperdatabase
    This is the lowest component of Roundup and is where all the issues, users, file attachments and messages are stored.
  2. Database schema
    This describes the content of the hyperdatabase - what fields are stored for issues, what user information, etc. Being stored in the instance, this allows it to be customised for a particular application. It also means that changes in the Roundup core code do not affect a running instance.
  3. Web Interface
    The web interface templates are defined in the instance too - and the actual CGI interface class is defined (mostly using base classes in the Roundup core code) so it, like the database, may be customised for each instance in use.
Instances are created using the roundup-admin tool.

Command Line Tool

To initiliase a new instance, run roundup-admin init. You will be asked a series of questions:
  1. Instance home directory
  2. Schema to use
  3. Database back-end to use
  4. Administration user "admin" password.
Roundup is configurable using a localconfig.py file in the instance home. It may have the following variable declarations:
  1. MAILHOST
    The SMTP mail host that roundup will use to send mail
  2. MAIL_DOMAIN
    The domain name used for email addresses
Any further configuration should be possible by editing the instance home's __init__.py directly.

The email addresses used by the system by default are:

  1. issue_tracker@MAIL_DOMAIN
    submissions of issues
  2. roundup-admin@MAIL_DOMAIN
    roundup's internal use (problems, etc)
Note: We run the instance as group "issue_tracker" and add the mail and web user ("mail" and "apache" on our RedHat 7.1 system) to that group, as well as any admin people.

E-Mail Interface

Set up a mail alias called "issue_tracker" as:
|/usr/bin/python /usr/local/bin/roundup-mailgw <instance_home>
In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh so sendmail will accept the pipe command. In that case, symlink /etc/smrsh/roundup-mailgw to /usr/local/bin/roundup-mailgw and change the command to:
|roundup-mailgw <instance_home>
To test the mail gateway on unix systems, try:
echo test |mail -s '[issue] test' issue_tracker@your.domain

Web Interface

This software will work through apache or stand-alone.

Stand-alone:

  1. Edit roundup-server at the top - ROUNDUP_INSTANCE_HOMES needs to know about your instance. *** command-line option
  2. roundup-server [hostname port] (hostname may be "")
  3. Load up the page /<instance name>/index where instance name is the name you nominated in ROUNDUP_INSTANCE_HOMES. *** command-line option
Apache:
  1. Make sure roundup.cgi is executable. Edit it at the top - ROUNDUP_INSTANCE_HOMES needs to know about your instance.
  2. Edit your /etc/httpd/conf/httpd.conf and make sure that the /home/httpd/html/roundup/roundup.cgi script will be treated as a CGI script.
  3. Add the following to your /etc/httpd/conf/httpd.conf: 
    ------8<------- snip here ------8<-------
RewriteEngine on
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule ^/roundup/roundup.cgi(.*) /home/httpd/html/roundup/roundup.cgi$1 [e=HTTP_CGI_AUTHORIZATION:%1,t=application/x-httpd-cgi,l]
------8<------- snip here ------8<-------
    note: the RewriteRule must be on one line - no breaks
  4. Re-start your apache to re-load the config
  5. Load up the page /roundup/roundup.cgi/<instance name>/index where instance name is the name you nominated in ROUNDUP_INSTANCE_HOMES.

Users

To add users, use one of the following interfaces:
  1. On the web, access the URL .../<instance name>/newuser to bring up a form which may be used to add a new user.
  2. On the command-line, use:
    roundup-admin -i <instance home> create user username=bozo password=bozo address=richard@clown.org
    Supply the admin username and password. roundup-admin will print the id of the new user.
  3. Any e-mail sent to roundup from an address that doesn't match an existing user in the database will result in a new user entry being created for that user.

Issues

To add issues, use one of the following interfaces:
  1. On the web, access the URL .../<instance name>/newissue to bring up a form which may be used to add a new issue.
  2. On the command-line, use:
    roundup-admin -i <instance home> create issue title="test issue"
    Supply the admin username and password. roundup-admin will print the id of the new issue.
  3. Any e-mail sent to roundup with the subject line containing [issue] will automatically created a new issue in the database using the contents of the e-mail.

Acknowledgements

Go Ping, you rock! Also, go Bizar Software for letting me implement this system on their time.