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