Roundup
                                    =======

Installation
===============
These instructions work on redhat 6.2 and mandrake 8.0 - with the caveat
that these systems don't come with python 2.1.1 or newer installed, so you'll
have to upgrade python before this stuff will work.


Prerequisites
-------------
Python 2.1.1 or newer.

Note: Python 2.1.1 shipped with SuSE7.3 might miss module _weakref.

You will need either the anydbm or bsddb module.


Testing the Software
--------------------

Either run "run_tests" or "python -c 'import test;test.go()'" and make sure 
there's no errors. If there are errors, please let us know!

Installing the Software
-----------------------

1. Run:

      python setup.py install

   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>

   The command:

      python setup.py install --help

   gives all the options available for installation.



Initial Setup
=============

The following instructions assume that you have installed roundup. If you
haven't, you may still proceed - the commands will change though. Where you
see:

   roundup-admin init

you will need to execute:

   PYTHONPATH=. python roundup/scripts/roundup_admin.py init

where "python" is your python 2.x interpreter ("python2" on redhat
systems). Note the dash is changed to an underscore - the same pattern
holds for the roundup-server and roundup-mailgw scripts.


Instance
--------
Run "roundup-admin init". This initialises a roundup instance.

Roundup is configurable using a localconfig.py file in the instance home.
It may have the following variable declarations:
  
  MAILHOST - The SMTP mail host that roundup will use to send mail
  MAIL_DOMAIN - The domain name used for email addresses

Any further configuration should be possible by editing the instance home's
instance_config.py directly.

The email addresses used by the system by default are:

  issue_tracker@MAIL_DOMAIN  - submissions of issues
  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.


Mail
----

Setup 1: As a mail alias pipe process
- - - - - - - - - - - - - - - - - - -
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 (include the quote marks):
  "|roundup-mailgw <instance_home>"

To test the mail gateway on unix systems, try:

  echo test |mail -s '[issue] test' issue_tracker@your.domain


Setup 2: As a regular cron job
- - - - - - - - - - - - - - - 
Set the roundup-mailgw up to run every 10 minutes or so. For example:
10 * * * * /usr/local/bin/roundup-mailgw <instance_home> <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".



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.
 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.

Apache:
 1. The CGI script is found in the cgi-bin directory of the roundup
    distribution.
 2. Make sure roundup.cgi is executable. Edit it at the top -
    ROUNDUP_INSTANCE_HOMES needs to know about your instance.
 3. 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.
 4. Re-start your apache to re-load the config if necessary.
 5. Load up the page "/roundup/roundup.cgi/<instance name>/index" where
    instance name is the name you nominated in ROUNDUP_INSTANCE_HOMES.
 6. To use the CGI script unchanged, which allows much easier updates,
    add these directives to your "httpd.conf":
        SetEnv ROUNDUP_LOG "/var/log/roundup.log"
        SetEnv ROUNDUP_INSTANCE_HOMES "Default=/usr/local/share/roundup/instances/Default"
        SetEnv ROUNDUP_DEBUG "0"
 7. On Windows, write a batch file "roundup.bat" similar to the one below
    and place it into your cgi-bin directory:
        @echo off
        set ROUNDUP_LOG=c:\Python21\share\roundup\cgi.log
        set ROUNDUP_INSTANCE_HOMES=Default=c:\Python21\share\roundup\instances\Default;
        set ROUNDUP_DEBUG=0
        c:\Python21\python.exe c:\Python21\share\roundup\cgi-bin\roundup.cgi