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 Either run "run_tests" or "python -c 'import test;test.go()'" and make sure
  24 there's no errors. 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 - the commands will change though. Where you
  51 see:
  52
  53    roundup-admin init
  54
  55 you will need to execute:
  56
  57    PYTHONPATH=. python roundup/scripts/roundup_admin.py init
  58
  59 where "python" is your python 2.x interpreter ("python2" on redhat
  60 systems). Note the dash is changed to an underscore - the same pattern
  61 holds for the roundup-server and roundup-mailgw scripts.
  62
  63
  64 Instance
  65 --------
  66 Run "roundup-admin init". This initialises a roundup instance.
  67
  68 Roundup is configurable using a localconfig.py file in the instance home.
  69 It may have the following variable declarations:
  70
  71   MAILHOST - The SMTP mail host that roundup will use to send mail
  72   MAIL_DOMAIN - The domain name used for email addresses
  73
  74 Any further configuration should be possible by editing the instance home's
  75 instance_config.py directly.
  76
  77 The email addresses used by the system by default are:
  78
  79   issue_tracker@MAIL_DOMAIN  - submissions of issues
  80   roundup-admin@MAIL_DOMAIN  - roundup's internal use (problems, etc)
  81
  82
  83 Note:
  84 We run the instance as group "issue_tracker" and add the mail and web user
  85 ("mail" and "apache" on our RedHat 7.1 system) to that group, as well as
  86 any admin people.
  87
  88
  89 Mail
  90 ----
  91
  92 Setup 1: As a mail alias pipe process
  93 - - - - - - - - - - - - - - - - - - -
  94 Set up a mail alias called "issue_tracker" as:
  95   "|/usr/bin/python /usr/local/bin/roundup-mailgw <instance_home>"
  96
  97 In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh
  98 so sendmail will accept the pipe command. In that case, symlink
  99 /etc/smrsh/roundup-mailgw to /usr/local/bin/roundup-mailgw and change the
 100 command to (include the quote marks):
 101   "|roundup-mailgw <instance_home>"
 102
 103 To test the mail gateway on unix systems, try:
 104
 105   echo test |mail -s '[issue] test' issue_tracker@your.domain
 106
 107
 108 Setup 2: As a regular cron job
 109 - - - - - - - - - - - - - - -
 110 Set the roundup-mailgw up to run every 10 minutes or so. For example:
 111 10 * * * * /usr/local/bin/roundup-mailgw <instance_home> <mail_spool_file>
 112
 113 Where the mail_spool_file argument is the location of the roundup
 114 submission user's mail spool. On most systems, the spool for a user
 115 "issue_tracker" will be "/var/mail/issue_tracker".
 116
 117
 118
 119 Web Interface
 120 -------------
 121 This software will work through apache or stand-alone.
 122
 123 Stand-alone:
 124  1. Edit roundup-server at the top - ROUNDUP_INSTANCE_HOMES needs to know
 125     about your instance.
 126  2. "roundup-server [hostname port]"   (hostname may be "")
 127  3. Load up the page "/<instance name>/index" where instance name is the
 128     name you nominated in ROUNDUP_INSTANCE_HOMES.
 129
 130 Apache:
 131  1. The CGI script is found in the cgi-bin directory of the roundup
 132     distribution.
 133  2. Make sure roundup.cgi is executable. Edit it at the top -
 134     ROUNDUP_INSTANCE_HOMES needs to know about your instance.
 135  3. Edit your /etc/httpd/conf/httpd.conf and make sure that the
 136     /home/httpd/html/roundup/roundup.cgi script will be treated as a CGI
 137     script.
 138  4. Re-start your apache to re-load the config if necessary.
 139  5. Load up the page "/roundup/roundup.cgi/<instance name>/index" where
 140     instance name is the name you nominated in ROUNDUP_INSTANCE_HOMES.
 141  6. To use the CGI script unchanged, which allows much easier updates,
 142     add these directives to your "httpd.conf":
 143         SetEnv ROUNDUP_LOG "/var/log/roundup.log"
 144         SetEnv ROUNDUP_INSTANCE_HOMES "Default=/usr/local/share/roundup/instances/Default"
 145         SetEnv ROUNDUP_DEBUG "0"
 146  7. On Windows, write a batch file "roundup.bat" similar to the one below
 147     and place it into your cgi-bin directory:
 148         @echo off
 149         set ROUNDUP_LOG=c:\Python21\share\roundup\cgi.log
 150         set ROUNDUP_INSTANCE_HOMES=Default=c:\Python21\share\roundup\instances\Default;
 151         set ROUNDUP_DEBUG=0
 152         c:\Python21\python.exe c:\Python21\share\roundup\cgi-bin\roundup.cgi
 153