Contents
There's two "installations" that we talk about when using Roundup:
The installation of the software and its support files. This uses the standard Python mechanism called "distutils" and thus Roundup's core code, executable scripts and support data files are installed in Python's directories. On Windows, this is typically:
<python dir>\scripts\...
<python dir>\lib\site-packages\roundup\...
<python dir>\share\roundup\...
and on Unix-like systems (eg. Linux):
<python root>/bin/...
<python root>/lib-<python version>/site-packages/roundup/...
<python root>/share/roundup/...
The installation of a specific tracker. When invoking the roundup-admin "inst" (and "init") commands, you're creating a new Roundup tracker. This installs configuration files, HTML templates, detector code and a new database. You have complete control over where this stuff goes through both choosing your "tracker home" and the main -> database variable in the tracker's config.ini.
You may configure where Roundup logs messages in your tracker's config.ini file. Roundup will use the standard Python (2.3+) logging implementation when available. If not, then a very basic logging implementation will be used (see BasicLogging in the roundup.rlog module for details).
(roundup-mailgw always logs to the tracker's log file)
In both cases, if no logfile is specified then logging will simply be sent to sys.stderr with only logging of ERROR messages.
The basic configuration file layout is as follows (take from the roundup-server.ini.example file in the "doc" directory):
[main] port = 8080 ;host = ;user = ;group = ;log_ip = yes ;pidfile = ;logfile = ;template = ;ssl = no ;pem = [trackers] ; Add one of these per tracker being served name = /path/to/tracker/name
Values ";commented out" are optional. The meaning of the various options are as follows:
Roundup holds its own user database which primarily contains a username, password and email address for the user. Roundup must have its own user listing, in order to maintain internal consistency of its data. It is a relatively simple exercise to update this listing on a regular basis, or on demand, so that it matches an external listing (eg. unix passwd file, LDAP, etc.)
Roundup identifies users in a number of ways:
In both cases, Roundup's behaviour when dealing with unknown users is controlled by Permissions defined in the "SECURITY SETTINGS" section of the tracker's schema.py module:
More information about how to customise your tracker's security settings may be found in the customisation documentation.
Maintenance of Roundup can involve one of the following:
The roundup-admin import and export commands are not recommended for performing backup.
Optionally stop the web and email frontends and to copy the contents of the tracker home directory to some other place using standard backup tools. This means using pg_dump to take a snapshot of your Postgres backend database, for example. A simple copy of the tracker home (and files storage area if you've configured it to be elsewhere) will then complete the backup.
Always make a backup of your tracker before upgrading software. Steps you may take:
Ensure that the unit tests run on your system:
python run_tests.py
If you're using an RDBMS backend, make a backup of its contents now.
Make a backup of the tracker home itself.
Stop the tracker web and email frontends.
Install the new version of the software:
python setup.py install
Follow the steps in the upgrading documentation for the new version of the software in the copied.
Usually you will be asked to run roundup_admin migrate on your tracker before you allow users to start accessing the tracker.
It's safe to run this even if it's not required, so just get into the habit.
Restart your tracker web and email frontends.
If something bad happens, you may reinstate your backup of the tracker and reinstall the older version of the sofware using the same install command:
python setup.py install
Stop the existing tracker web and email frontends (preventing changes).
Use the roundup-admin tool "export" command to export the contents of your tracker to disk.
Copy the tracker home to a new directory.
Delete the "db" directory from the new directory.
Enter the new backend name in the tracker home db/backend_name file.
Use the roundup-admin "import" command to import the previous export with the new tracker home. If non-interactively:
roundup-admin -i <tracker home> import <tracker export dir>
If interactively, enter 'commit' before exitting.
Test each of the admin tool, web interface and mail gateway using the new backend.
Move the old tracker home out of the way (rename to "tracker.old") and move the new tracker home into its place.
Restart web and email frontends.
If you're moving the tracker to a similar machine, you should:
Most of the backends are actually portable across platforms (ie. from Unix to Windows to Mac). If this isn't the case (ie. the tracker doesn't work when moved using the above steps) then you'll need to:
You have a couple of choices. You can either use a CSV import into Roundup, or you can write a simple Python script which uses the Roundup API directly. The latter is almost always simpler -- see the "scripts" directory in the Roundup source for some example uses of the API.
"roundup-admin import" will import data into your tracker from a directory containing files with the following format:
one colon-separated-values file per Class with columns for each property, named <classname>.csv
one colon-separated-values file per Class with journal information, named <classname>-journals.csv (this is required, even if it's empty)
if the Class is a FileClass, you may have the "content" property stored in separate files from the csv files. This goes in a directory structure:
<classname>-files/<N>/<designator>
where <designator> is the item's <classname><id> combination. The <N> value is int(<id> / 1000).
The roundup-admin program can create any data you wish to in the database. To create a new user, use:
roundup-admin create user
To figure out what good values might be for some of the fields (eg. Roles) you can just display another user:
roundup-admin list user
(or if you know their username, and it happens to be "richard"):
roundup-admin find username=richard
then using the user id you get from one of the above commands, you may display the user's details:
roundup-admin display <userid>
On Unix systems, use the scripts/server-ctl script to control the roundup-server server. Copy it somewhere and edit the variables at the top to reflect your specific installation.
On Windows, the roundup-server program runs as a Windows Service, and therefore may be controlled through the Services control panel. The roundup-server program may also control the service directly:
To bring up the services panel:
You will need a server configuration file (as described in Configuring roundup-server) for specifying tracker homes and other roundup-server configuration. Specify the name of this file using the -C switch when installing the service.
The mail gateway script should be scheduled to run regularly on your Windows server. Normally this will result in a window popping up. The solution to this is to: