Classic Template

The classic template is the one defined in the Roundup Specification. It holds issues which have priorities and statuses. Each issue may also have a set of messages which are disseminated to the issue’s list of nosy users.

Minimal Template

The minimal template has the minimum setup required for a tracker installation. That is, it has the configuration files, defines a user database and the basic HTML interface to that. It’s a completely clean slate for you to create your tracker on.

Web Server cgi-bin

A benefit of using the cgi-bin approach is that it’s the easiest way to restrict access to your tracker to only use HTTPS. Access will be slower than through the stand-alone web server though.

If your Python isn’t installed as “python” then you’ll need to edit the roundup.cgi script to fix the first line.

If you’re using IIS on a Windows platform, you’ll need to run this command for the cgi to work (it turns on the PATH_INFO cgi variable):

adsutil.vbs set w3svc/AllowPathInfoForScriptMappings TRUE

The adsutil.vbs file can be found in either c:\inetpub\adminscripts or c:\winnt\system32\inetsrv\adminsamples\ or c:\winnt\system32\inetsrv\adminscripts\ depending on your installation.

More information about ISS setup may be found at:

http://support.microsoft.com/default.aspx?scid=kb%3Ben-us%3B276494

Copy the frontends/roundup.cgi file to your web server’s cgi-bin directory. You will need to configure it to tell it where your tracker home is. You can do this either:

Through an environment variable

Set the variable TRACKER_HOMES to be a colon (“:”) separated list of name=home pairs (if you’re using apache, the SetEnv directive can do this)

Directly in the roundup.cgi file itself

Add your instance to the TRACKER_HOMES variable as 'name': 'home'

The “name” part of the configuration will appear in the URL and identifies the tracker (so you may have more than one tracker per cgi-bin script). Make sure there are no spaces or other illegal characters in it (to be safe, stick to letters and numbers). The “name” forms part of the URL that appears in the tracker config “tracker :: web” variable, so make sure they match. The “home” part of the configuration is the tracker home directory.

If you’re using Apache, you can use an additional trick to hide the .cgi extension of the cgi script. Place the roundup.cgi script wherever you want it to be, rename it to just roundup, and add a couple lines to your Apache configuration:

<Location /path/to/roundup>
  SetHandler cgi-script
</Location>

CGI-bin for Limited-Access Hosting

If you are running in a shared-hosting environment or otherwise don’t have permission to edit the system web server’s configuration, but can create a .htaccess file then you may be able to use this approach.

1. Install flup

2. Create a script roundup_stub in your server’s cgi-bin directory containing:

   #!/usr/bin/env python
   
   # if necessary modify the Python path to include the place you
   # installed Roundup
   #import sys
   #sys.path.append('...')
   
   # cgitb is needed for debugging in browser only
   #import cgitb
   #cgitb.enable()
   
   # obtain the WSGI request dispatcher
   from roundup.cgi.wsgi_handler import RequestDispatcher
   tracker_home = '/path/to/tracker/home'
   app = RequestDispatcher(tracker_home)
   
   from flup.server.cgi import WSGIServer
   WSGIServer(app).run()
   

3. Modify or created the .htaccess file in the desired (sub-)domain directory to contain:

   RewriteEngine On
   RewriteBase /
   RewriteRule ^(.*)$      /cgi-bin/roundup_stub/$1 [L]

Now loading the (sub-)domain in a browser should load the tracker web interface. If you get a “500” error then enable the “cgitb” lines in the stub to get some debugging information.

Stand-alone Web Server

This approach will give you faster response than cgi-bin. You may investigate using ProxyPass or similar configuration in apache to have your tracker accessed through the same URL as other systems.

The stand-alone web server is started with the command roundup-server. It has several options - display them with roundup-server -h.

The tracker home configuration is similar to the cgi-bin - you may either edit the script to change the TRACKER_HOMES variable or you may supply the name=home values on the command-line after all the other options.

To make the server run in the background, use the “-d” option, specifying the name of a file to write the server process id (pid) to.

Zope Product - ZRoundup

ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to your Products directory either in INSTANCE_HOME/Products or the Zope code tree lib/python/Products.

When you next (re)start up Zope, you will be able to add a ZRoundup object that interfaces to your new tracker.

Apache HTTP Server with mod_python

Mod_python is an Apache module that embeds the Python interpreter within the server. Running Roundup this way is much faster than all above options and, like web server cgi-bin, allows you to use HTTPS protocol. The drawback is that this setup is more complicated.

The following instructions were tested on apache 2.0 with mod_python 3.1. If you are using older versions, your mileage may vary.

Mod_python uses OS threads. If your apache was built without threads (quite commonly), you must load the threading library to run mod_python. This is done by setting LD_PRELOAD to your threading library path in apache envvars file. Example for gentoo linux (envvars file is located in /usr/lib/apache2/build/):

LD_PRELOAD=/lib/libpthread.so.0
export LD_PRELOAD

Example for FreeBSD (envvars is in /usr/local/sbin/):

LD_PRELOAD=/usr/lib/libc_r.so
export LD_PRELOAD

Next, you have to add Roundup trackers configuration to apache config. Roundup apache interface uses the following options specified with PythonOption directives:

TrackerHome:

defines the tracker home directory - the directory that was specified when you did roundup-admin init. This option is required.

TrackerLanguage:

defines web user interface language. mod_python applications do not receive OS environment variables in the same way as command-line programs, so the language cannot be selected by setting commonly used variables like LANG or LC_ALL. TrackerLanguage value has the same syntax as values of these environment variables. This option may be omitted.

TrackerDebug:

run the tracker in debug mode. Setting this option to yes or true has the same effect as running roundup-server -t debug: the database schema and used html templates are rebuilt for each HTTP request. Values no or false mean that all html templates for the tracker are compiled and the database schema is checked once at startup. This is the default behaviour.

TrackerTiming:

has nearly the same effect as environment variable CGI_SHOW_TIMING for standalone roundup server. The difference is that setting this option to no or false disables timings display. Value comment writes request handling times in html comment, and any other non-empty value makes timing report visible. By default, timing display is disabled.

In the following example we have two trackers set up in /var/db/roundup/support and /var/db/roundup/devel and accessed as https://my.host/roundup/support/ and https://my.host/roundup/devel/ respectively (provided Apache has been set up for SSL of course). Having them share same parent directory allows us to reduce the number of configuration directives. Support tracker has russian user interface. The other tracker (devel) has english user interface (default).

Static files from html directory are served by apache itself - this is quicker and generally more robust than doing that from python. Everything else is aliased to dummy (non-existing) py file, which is handled by mod_python and our roundup module.

Example mod_python configuration:

#################################################
# Roundup Issue tracker
#################################################
# enable Python optimizations (like 'python -O')
PythonOptimize On
# let apache handle static files from 'html' directories
AliasMatch /roundup/(.+)/@@file/(.*) /var/db/roundup/$1/html/$2
# everything else is handled by roundup web UI
AliasMatch /roundup/([^/]+)/(?!@@file/)(.*) /var/db/roundup/$1/dummy.py/$2
# roundup requires a slash after tracker name - add it if missing
RedirectMatch permanent ^/roundup/([^/]+)$ /roundup/$1/
# common settings for all roundup trackers
<Directory /var/db/roundup/*>
  Order allow,deny
  Allow from all
  AllowOverride None
  Options None
  AddHandler python-program .py
  PythonHandler roundup.cgi.apache
  # uncomment the following line to see tracebacks in the browser
  # (note that *some* tracebacks will be displayed anyway)
  #PythonDebug On
</Directory>
# roundup tracker homes
<Directory /var/db/roundup/support>
  PythonOption TrackerHome /var/db/roundup/support
  PythonOption TrackerLanguage ru
</Directory>
<Directory /var/db/roundup/devel>
  PythonOption TrackerHome /var/db/roundup/devel
</Directory>

Notice that the /var/db/roundup path shown above refers to the directory in which the tracker homes are stored. The actual value will thus depend on your system.

On Windows the corresponding lines will look similar to these:

AliasMatch /roundup/(.+)/@@file/(.*) C:/DATA/roundup/$1/html/$2
AliasMatch /roundup/([^/]+)/(?!@@file/)(.*) C:/DATA/roundup/$1/dummy.py/$2
<Directory C:/DATA/roundup/*>
<Directory C:/DATA/roundup/support>
<Directory C:/DATA/roundup/devel>

In this example the directory hosting all of the tracker homes is C:\DATA\roundup. (Notice that you must use forward slashes in paths inside the httpd.conf file!)

The URL for accessing these trackers then become: http://<roundupserver>/roundup/support/` and http://<roundupserver>/roundup/devel/

Note that in order to use https connections you must set up Apache for secure serving with SSL.

WSGI Handler

The WSGI handler is quite simple. The following sample code shows how to use it:

from wsgiref.simple_server import make_server

# obtain the WSGI request dispatcher
from roundup.cgi.wsgi_handler import RequestDispatcher
tracker_home = 'demo'
app = RequestDispatcher(tracker_home)

httpd = make_server('', 8917, app)
httpd.serve_forever()

To test the above you should create a demo tracker with python demo.py. Edit the config.ini to change the web URL to “http://localhost:8917/“.

As a mail alias pipe process

Set up a mail alias called “issue_tracker” as (include the quote marks): “|/usr/bin/python /usr/bin/roundup-mailgw <tracker_home>” (substitute /usr/bin for wherever roundup-mailgw is installed).

In some installations (e.g. RedHat Linux and Fedora Core) you’ll need to set up smrsh so sendmail will accept the pipe command. In that case, symlink /etc/smrsh/roundup-mailgw to “/usr/bin/roundup-mailgw” and change the command to:

|roundup-mailgw /opt/roundup/trackers/support

To test the mail gateway on unix systems, try:

echo test |mail -s '[issue] test' support@YOUR_DOMAIN_HERE

Be careful that some mail systems (postfix for example) will impost a limits on processes they spawn. In particular postfix can set a file size limit. This can cause your Roundup database to become corrupted.

As a custom router/transport using a pipe process (Exim4 specific)

The following configuration snippets for Exim 4 configuration implement a custom router & transport to accomplish mail delivery to roundup-mailgw. A configuration for Exim3 is similar but not included, since Exim3 is considered obsolete.

This configuration is similar to the previous section, in that it uses a pipe process. However, there are advantages to using a custom router/transport process, if you are using Exim.

• This avoids privilege escalation, since otherwise the pipe process will run as the mail user, typically mail. The transport can be configured to run as the user appropriate for the task at hand. In the transport described in this section, Exim4 runs as the unprivileged user roundup.
• Separate configuration is not required for each tracker instance. When a email arrives at the server, Exim passes it through the defined routers. The roundup_router looks for a match with one of the roundup directories, and if there is one it is passed to the roundup_transport, which uses the pipe process described in the previous section (As a mail alias pipe process).

The matching is done in the line:

require_files = /usr/bin/roundup-mailgw:ROUNDUP_HOME/$local_part/schema.py

The following configuration has been tested on Debian Sarge with Exim4.

This config makes a few assumptions:

• That the mail address corresponding to the tracker instance has the same name as the directory of the tracker instance, i.e. the mail interface address corresponding to a Roundup instance called /var/lib/roundup/trackers/mytracker is mytracker@your.host.
• That (at least) all the db subdirectories of all the tracker instances (ie. /var/lib/roundup/trackers/*/db) are owned by the same user, in this case, ‘roundup’.
• That if the schema.py file exists, then the tracker is ready for use. Another option is to use the config.ini file (this changed in 0.8 from config.py).

Macros for Roundup router/transport. Should be placed in the macros section of the Exim4 config:

# Home dir for your Roundup installation
ROUNDUP_HOME=/var/lib/roundup/trackers

# User and group for Roundup.
ROUNDUP_USER=roundup
ROUNDUP_GROUP=roundup

Custom router for Roundup. This will (probably) work if placed at the beginning of the router section of the Exim4 config:

roundup_router:
    driver = accept
    # The config file config.ini seems like a more natural choice, but the
    # file config.py was replaced by config.ini in 0.8, and schema.py needs
    # to be present too.
    require_files = /usr/bin/roundup-mailgw:ROUNDUP_HOME/$local_part/schema.py
    transport = roundup_transport

Custom transport for Roundup. This will (probably) work if placed at the beginning of the router section of the Exim4 config:

roundup_transport:
    driver = pipe
    command = /usr/bin/python /usr/bin/roundup-mailgw ROUNDUP_HOME/$local_part/
    current_directory = ROUNDUP_HOME
    home_directory = ROUNDUP_HOME
    user = ROUNDUP_USER
    group = ROUNDUP_GROUP

As a regular job using a mailbox source

Set roundup-mailgw up to run every 10 minutes or so. For example (substitute /usr/bin for wherever roundup-mailgw is installed):

0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support mailbox <mail_spool_file>

Where the mail_spool_file argument is the location of the roundup submission user’s mail spool. On most systems, the spool for a user “issue_tracker” will be “/var/mail/issue_tracker“.

As a regular job using a POP source

To retrieve from a POP mailbox, use a cron entry similar to the mailbox one (substitute /usr/bin for wherever roundup-mailgw is installed):

0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support pop <pop_spec>

where pop_spec is “username:password@server” that specifies the roundup submission user’s POP account name, password and server.

On windows, you would set up the command using the windows scheduler.

As a regular job using an IMAP source

To retrieve from an IMAP mailbox, use a cron entry similar to the POP one (substitute /usr/bin for wherever roundup-mailgw is installed):

0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support imap <imap_spec>

where imap_spec is “username:password@server” that specifies the roundup submission user’s IMAP account name, password and server. You may optionally include a mailbox to use other than the default INBOX with “imap username:password@server mailbox“.

If you have a secure (ie. HTTPS) IMAP server then you may use imaps in place of imap in the command to use a secure connection.

As with the POP job, on windows, you would set up the command using the windows scheduler.

1. Using the Windows scheduler

Set up the following in Scheduled Tasks (note, the following is for a cygwin setup):

Run

c:\cygwin\bin\bash.exe -c "roundup-server TheProject=/opt/roundup/trackers/support"

Start In

C:\cygwin\opt\roundup\bin

Schedule

At System Startup

To have the Roundup mail gateway run periodically to poll a POP email address, set up the following in Scheduled Tasks:

Run

c:\cygwin\bin\bash.exe -c "roundup-mailgw /opt/roundup/trackers/support pop roundup:roundup@mail-server"

Start In

C:\cygwin\opt\roundup\bin

Schedule

Every 10 minutes from 5:00AM for 24 hours every day

Stop the task if it runs for 8 minutes

2. Installing the roundup server as a Windows service

This is more Windows oriented and will make the Roundup server run as soon as the PC starts up without any need for a login or such. It will also be available in the normal Windows Administrative Tools.

For this you need first to create a service ini file containing the relevant settings.

1. It is created if you execute the following command from within the scripts directory (notice the use of backslashes):

   roundup-server -S -C <trackersdir>\server.ini -n <servername> -p 8080 -l <trackersdir>\trackerlog.log software=<trackersdir>\Software

   where the item <trackersdir> is replaced with the physical directory that hosts all of your trackers. The <servername> item is the name of your roundup server PC, such as w2003srv or similar.

2. Next open the now created file C:\DATA\roundup\server.ini file (if your <trackersdir> is C:\DATA\roundup). Check the entries for correctness, especially this one:

   [trackers]
   software = C:\DATA\Roundup\Software

   (this is an example where the tracker is named software and its home is C:\DATA\Roundup\Software)

3. Next give the commands that actually installs and starts the service:

   roundup-server -C C:\DATA\Roundup\server.ini -c install
   roundup-server -c start

4. Finally open the AdministrativeTools/Services applet and locate the Roundup service entry. Open its properties and change it to start automatically instead of manually.

If you are using Apache as the webserver you might want to use it with mod_python instead to serve out Roundup. In that case see the mod_python instructions above for details.