INSTALL.txt

   1                                     Roundup
   2                                     =======
   3
   4 Installation
   5 ===============
   6 These instructions work on redhat 6.2 and mandrake 8.0 - with the caveat
   7 that these systems don't come with python 2.1.1 or newer installed, so you'll
   8 have to upgrade python before this stuff will work.
   9
  10
  11 Prerequisites
  12 -------------
  13 Python 2.1.1 or newer.
  14
  15 Note: Python 2.1.1 shipped with SuSE7.3 might miss module _weakref.
  16
  17 You will need either the anydbm or bsddb module.
  18
  19
  20 Testing the Software
  21 --------------------
  22
  23 Run "python -c 'import test;test.go()'" and make sure there's no errors.
  24 If there are errors, please let us know!
  25
  26 Installing the Software
  27 -----------------------
  28
  29 1. Run:
  30
  31       python setup.py install
  32
  33    If you would prefer the scripts installed in somewhere other than
  34    /usr/local/bin, add "--install-scripts=<dir>" to the command:
  35
  36       python setup.py install --install-scripts=<dir>
  37
  38    The command:
  39
  40       python setup.py install --help
  41
  42    gives all the options available for installation.
  43
  44
  45
  46 Initial Setup
  47 =============
  48
  49 The following instructions assume that you have installed roundup. If you
  50 haven't, you may still proceed - just preface all commands with "./"
  51 ie. "./roundup-admin init".
  52
  53
  54 Instance
  55 --------
  56 Run "roundup-admin init". This initialises a roundup instance.
  57
  58 Roundup is configurable using a localconfig.py file in the instance home.
  59 It may have the following variable declarations:
  60
  61   MAILHOST - The SMTP mail host that roundup will use to send mail
  62   MAIL_DOMAIN - The domain name used for email addresses
  63
  64 Any further configuration should be possible by editing the instance home's
  65 instance_config.py directly.
  66
  67 The email addresses used by the system by default are:
  68
  69   issue_tracker@MAIL_DOMAIN  - submissions of issues
  70   roundup-admin@MAIL_DOMAIN  - roundup's internal use (problems, etc)
  71
  72
  73 Note:
  74 We run the instance as group "issue_tracker" and add the mail and web user
  75 ("mail" and "apache" on our RedHat 7.1 system) to that group, as well as
  76 any admin people.
  77
  78
  79 Mail
  80 ----
  81
  82 Setup 1: As a mail alias pipe process
  83 - - - - - - - - - - - - - - - - - - -
  84 Set up a mail alias called "issue_tracker" as:
  85   "|/usr/bin/python /usr/local/bin/roundup-mailgw <instance_home>"
  86
  87 In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh
  88 so sendmail will accept the pipe command. In that case, symlink
  89 /etc/smrsh/roundup-mailgw to /usr/local/bin/roundup-mailgw and change the
  90 command to (include the quote marks):
  91   "|roundup-mailgw <instance_home>"
  92
  93 To test the mail gateway on unix systems, try:
  94
  95   echo test |mail -s '[issue] test' issue_tracker@your.domain
  96
  97
  98 Setup 2: As a regular cron job
  99 - - - - - - - - - - - - - - -
 100 Set the roundup-mailgw up to run every 10 minutes or so. For example:
 101 10 * * * * /usr/local/bin/roundup-mailgw <instance_home> <mail_spool_file>
 102
 103 Where the mail_spool_file argument is the location of the roundup
 104 submission user's mail spool. On most systems, the spool for a user
 105 "issue_tracker" will be "/var/mail/issue_tracker".
 106
 107
 108
 109 Web Interface
 110 -------------
 111 This software will work through apache or stand-alone.
 112
 113 Stand-alone:
 114  1. Edit roundup-server at the top - ROUNDUP_INSTANCE_HOMES needs to know
 115     about your instance.
 116  2. "roundup-server [hostname port]"   (hostname may be "")
 117  3. Load up the page "/<instance name>/index" where instance name is the
 118     name you nominated in ROUNDUP_INSTANCE_HOMES.
 119
 120 Apache:
 121  1. The CGI script is found in the cgi-bin directory of the roundup
 122     distribution.
 123  2. Make sure roundup.cgi is executable. Edit it at the top -
 124     ROUNDUP_INSTANCE_HOMES needs to know about your instance.
 125  3. Edit your /etc/httpd/conf/httpd.conf and make sure that the
 126     /home/httpd/html/roundup/roundup.cgi script will be treated as a CGI
 127     script.
 128  4. Re-start your apache to re-load the config if necessary.
 129  5. Load up the page "/roundup/roundup.cgi/<instance name>/index" where
 130     instance name is the name you nominated in ROUNDUP_INSTANCE_HOMES.
 131  6. To use the CGI script unchanged, which allows much easier updates,
 132     add these directives to your "httpd.conf":
 133         SetEnv ROUNDUP_LOG "/var/log/roundup.log"
 134         SetEnv ROUNDUP_INSTANCE_HOMES "Default=/usr/local/share/roundup/instances/Default"
 135         SetEnv ROUNDUP_DEBUG "0"
 136  7. On Windows, write a batch file "roundup.bat" similar to the one below
 137     and place it into your cgi-bin directory:
 138         @echo off
 139         set ROUNDUP_LOG=c:\Python21\share\roundup\cgi.log
 140         set ROUNDUP_INSTANCE_HOMES=Default=c:\Python21\share\roundup\instances\Default;
 141         set ROUNDUP_DEBUG=0
 142         c:\Python21\python.exe c:\Python21\share\roundup\cgi-bin\roundup.cgi
 143