Maintenance
Read the separate administration guide for information about how to perform common maintenance tasks with Roundup.
Version: | 1.76 |
---|
Broken out separately, there are several conceptual pieces to a Roundup installation:
Roundup requires Python 2.1.3 or newer with a functioning anydbm module. Download the latest version from http://www.python.org/. It is highly recommended that users install the latest patch version of python as these contain many fixes to serious bugs.
If you're on windows, you will either need to be using the ActiveState python distribution (at http://www.activestate.com/Products/ActivePython/), or you'll have to install the win32all package separately (get it from http://starship.python.net/crew/mhammond/win32/).
If you're using a version of Python older than 2.3, you may need to install the "CSV" module.
Hint
CSV stands for Comma-Separated-Value. These files are used by all manner of programs (eg. spreadsheets) to exchange data.The "CSV" module is required if you wish to import or export data in the tracker, or if you wish to use the online generic class editing facility.
If you're using a version of Python older than 2.3, then you will need to install the "CSV" module from Object Craft. Users of Python2.3 and later don't need to. If you have a C compiler installed, then download the source and follow their installation instructions (simply python setup.py install.)
If you're on Windows and don't have a C compiler, then you'll need to download the pre-compiled csv.pyd file and install it. To install, just copy it to your Python installation in the lib\site-packages directory. For Python 2.2, this would be:
c:\python22\lib\site-packages
Once the CSV module is installed, you must restart roundup-server if it is already running, or the new module won't be detected.
If you're on some other platform and don't have a C compiler, you'll need to ask for help on the roundup-users mailing list.
Note
Some systems, such as Debian and NetBSD, already have Roundup installed. Try running the command "roundup-admin" with no arguments, and if it runs you may skip the Basic Installation Steps below and go straight to configuring your first tracker.Download the latest version from http://roundup.sf.net/.
If you're using WinZIP's "classic" interface, make sure the "Use folder names" check box is checked before you extract the files.
Note
The demo.py script is packaged in Roundup's source distribution - users of the Windows installer, other binary distributions or pre-installed Roundup will need to download the source to use it.If you just want to give Roundup a whirl Right Now, then simply run python demo.py. This will set up a simple demo tracker on your machine. When it's done, it'll print out a URL to point your web browser at so you may start playing. Three users will be set up:
Set aside 15-30 minutes. There's several steps to follow in your installation:
For information about how Roundup installs, see the administration guide.
To install the Roundup support code into your Python tree and Roundup scripts into /usr/local/bin (substitute that path for whatever is appropriate on your system). You need to have write permissions for these locations, eg. being root on unix:
python setup.py install
If you would like to place the Roundup scripts in a directory other than /usr/local/bin, then specify the preferred location with --install-script. For example, to install them in /opt/roundup/bin:
python setup.py install --install-scripts=/opt/roundup/bin
You can also use the --prefix option to use a completely different base directory, if you do not want to use administrator rights. If you choose to do this, you may have to change Python's search path (sys.path) yourself.
To create a Roundup tracker (necessary to do before you can use the software in any real fashion), you need to set up a "tracker home":
(Optional) If you intend to keep your roundup trackers under one top level directory which does not exist yet, you should create that directory now. Example:
mkdir /opt/roundup/trackers
Either add the Roundup script location to your PATH environment variable or specify the full path to the command in the next step.
Install a new tracker with the command roundup-admin install. You will be asked a series of questions. Descriptions of the provided templates can be found in choosing your template below. Descriptions of the available backends can be found in choosing your backend below. The questions will be something like (you may have more templates or backends available):
Enter tracker home: /opt/roundup/trackers/support Templates: classic Select template [classic]: classic Back ends: anydbm, mysql, sqlite Select backend [anydbm]: anydbm
Note: "Back ends" selection list depends on availability of third-party database modules. Standard python distribution includes anydbm module only.
The "support" part of the tracker name can be anything you want - it is going to be used as the directory that the tracker information will be stored in.
You will now be directed to edit the tracker configuration and initial schema. At a minimum, you must set MAILHOST, TRACKER_WEB, MAIL_DOMAIN and ADMIN_EMAIL. The configuration file uses Python syntax, so almost every value must be 'quoted' using single or double quotes. If you get stuck, and get configuration file errors, then see the tracker configuration section of the customisation documentation.
If you just want to get set up to test things quickly (and follow the instructions in step 3 below), you can even just set the TRACKER_WEB variable to:
TRACKER_WEB = 'http://localhost:8080/support/'
The URL must end in a '/', or your web interface will not work. See Customising Roundup for details on configuration and schema changes. You may change any of the configuration after you've initialised the tracker - it's just better to have valid values for this stuff now.
Initialise the tracker database with roundup-admin initialise. You will need to supply an admin password at this step. You will be prompted:
Admin Password: Confirm:
Note: running this command will destroy any existing data in the database. In the case of MySQL and PostgreSQL, any exsting database will be dropped and re-created.
Once this is done, the tracker has been created.
At this point, your tracker is set up, but doesn't have a nice user interface. To set that up, we need to configure a web interface and optionally configure an email interface. If you want to try your new tracker out, assuming TRACKER_WEB is set to 'http://localhost:8080/support/', run:
roundup-server support=/opt/roundup/trackers/support
then direct your web browser at:
and you should see the tracker interface.
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.
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.
The actual storage of Roundup tracker information is handled by backends. There's several to choose from, each with benefits and limitations:
Name | Speed | Users | Support |
---|---|---|---|
anydbm | Slowest | Few | Always available |
sqlite | Fastest(*) | Few | Needs install (PySQLite) |
metakit | Fastest(*) | Few | Needs install (metakit) |
postgresql | Fast | Many | Needs install/admin (psycopg) |
mysql | Fast | Many | Needs install/admin (MySQLdb) |
You may defer your decision by setting your tracker up with the anydbm backend (which is guaranteed to be available) and switching to one of the other backends at any time using the instructions in the administration guide.
Regardless of which backend you choose, Roundup will attempt to initialise a new database for you when you run the roundup-admin "initialise" command. In the case of MySQL and PostgreSQL you will need to have the appropriate privileges to create databases.
There are three web interfaces to choose from:
You may need to give the web server user permission to access the tracker home - see the UNIX environment steps for information. You may also need to configure your system in some way - see platform-specific notes.
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 install 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 cgi-bin/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:
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, renamed it to just roundup, and add a couple lines to your Apache configuration:
<Location /path/to/roundup> SetHandler cgi-script </Location>
This approach will give you the fastest of the three web interfaces. 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.
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.
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 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 two 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.
- TrackerLaguage:
- 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. 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 quickier 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>
If you don't want to use the email component of Roundup, then remove the "nosyreaction.py" module from your tracker "detectors" directory.
See platform-specific notes for steps that may be needed on your system.
There are three supported ways to get emailed issues into the Roundup tracker. You should pick ONE of the following, all of which will continue my example setup from above:
Set up a mail alias called "issue_tracker" as (include the quote marks): "|/usr/bin/python /usr/local/bin/roundup-mailgw <tracker_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 /opt/roundup/trackers/support
To test the mail gateway on unix systems, try:
echo test |mail -s '[issue] test' support@YOUR_DOMAIN_HERE
Set roundup-mailgw up to run every 10 minutes or so. For example:
0,10,20,30,40,50 * * * * /usr/local/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".
To retrieve from a POP mailbox, use a cron entry similar to the mailbox one:
0,10,20,30,40,50 * * * * /usr/local/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.
To retrieve from an IMAP mailbox, use a cron entry similar to the POP one:
0,10,20,30,40,50 * * * * /usr/local/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.
Each tracker ideally should have its own UNIX group, so create a UNIX group (edit /etc/group or your appropriate NIS map if you're using NIS). To continue with my examples so far, I would create the UNIX group 'support', although the name of the UNIX group does not have to be the same as the tracker name. To this 'support' group I then add all of the UNIX usernames who will be working with this Roundup tracker. In addition to 'real' users, the Roundup email gateway will need to have permissions to this area as well, so add the user your mail service runs as to the group (typically "mail" or "daemon"). The UNIX group might then look like:
support:*:1002:jblaine,samh,geezer,mail
If you intend to use the web interface (as most people do), you should also add the username your web server runs as to the group. My group now looks like this:
support:*:1002:jblaine,samh,geezer,mail,apache
The tracker "db" directory should be chmod'ed g+sw so that the group can write to the database, and any new files created in the database will be owned by the group.
If you're using the mysql or postgresql backend then you'll need to ensure that the tracker user has appropriate permissions to create/modify the database. If you're using roundup.cgi, the apache user needs permissions to modify the database. Alternatively, explicitly specify a database login in rdbms -> user and password in config.ini.
An alternative to the above is to create a new user who has the sole responsibility of running roundup. This user:
If you intend to send messages to Roundup that use Chinese, Japanese or Korean encodings the you'll need to obtain CJKCodecs from http://cjkpython.berlios.de/
Read the separate administration guide for information about how to perform common maintenance tasks with Roundup.
Read the separate upgrading document, which describes the steps needed to upgrade existing tracker trackers for each version of Roundup that is released.
If you intend to use Roundup with anything other than the defualt templates, if you would like to hack on Roundup, or if you would like implementation details, you should read Customising Roundup.
Things to think about before you jump off the deep end and install multiple trackers, which involve additional URLs, user databases, email addresses, databases to back up, etc.
To make the command-line tools accessible in Windows, you need to update the "Path" environment variable in the Registry via a dialog box.
On Windows 2000 and later:
Where <dir> in 7) is the root directory (e.g., C:\Python22\Scripts) of your Python installation.
I understand that in XP, 2) above is not needed as "Control Panel" is directly accessible from "Start".
I do not believe this is possible to do in previous versions of Windows.
To have the Roundup web server start up when your machine boots up, set the following up in Scheduled Tasks (note, the following is for a cygwin setup):
To have the Roundup mail gateway run periodically to poll a POP email address, set the following up in Scheduled Tasks:
If you use Sendmail's smrsh mechanism, you will need to tell smrsh that roundup-mailgw is a valid/trusted mail handler before it will work.
This is usually done via the following 2 steps:
Make sure you read the instructions under UNIX environment steps.
Python 2.1.1 as shipped with SuSE7.3 might be missing module _weakref.
You'll need to build Python.
Make sure you read the instructions under UNIX environment steps.
Note
The run_tests.py script is packaged in Roundup's source distribution - users of the Windows installer, other binary distributions or pre-installed Roundup will need to download the source to use it.Once you've unpacked roundup's source, run python run_tests.py in the source directory and make sure there are no errors. If there are errors, please let us know!
If the above fails, you may be using the wrong version of python. Try python2 run_tests.py. If that works, you will need to substitute python2 for python in all further commands you use in relation to Roundup -- from installation and scripts.
Back to Table of Contents
Next: User Guide