![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/INSTALL.txt b/INSTALL.txt
index 878abe94b684f9e8454c8da19b4dc7b966e3e5a3..2fbe7842350d17114954a3fbf5aa2277e970484f 100644 (file)
--- a/INSTALL.txt
+++ b/INSTALL.txt
Installation
===============
These instructions work on redhat 6.2 and mandrake 8.0 - with the caveat
-that these systems don't come with python 2.0 or newer installed, so you'll
+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
-------------
-Either:
- . Python 2.0 with pydoc installed. See http://www.lfw.org/ for pydoc.
-or
- . Python 2.1
+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
--------------------
-Run "python -c 'import tests;tests.go()'" and make sure there's no errors.
-If there are errors, please let us know!
-
+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. "./setup.py install"
-2. At present, the programs aren't installed, so you will need to copy:
- roundup-admin
- roundup-mailgw
- roundup-server
- to /usr/local/bin if you wish to have them installed.
+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 - just preface all commands with "./"
+ie. "./roundup-admin init".
+
+
Instance
--------
-Try "./roundup-admin init" :)
+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:
MAIL_DOMAIN - The domain name used for email addresses
Any further configuration should be possible by editing the instance home's
-__init__.py directly.
+instance_config.py directly.
The email addresses used by the system by default are:
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 /home/httpd/html/roundup/roundup-mailgw <instance_home>"
+ "|/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/python to /usr/bin/python and change the command to:
- "|python /home/httpd/html/roundup/roundup-mailgw <instance_home>"
+/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
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 "/" using the port number you set.
+ 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. Make sure roundup.cgi is executable. Edit it at the top -
+ 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.
- 2. Edit your /etc/httpd/conf/httpd.conf and make sure that the
+ 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.
- 3. Add the following to your /etc/httpd/conf/httpd.conf:
-------8<------- snip here ------8<-------
-RewriteEngine on
-RewriteCond %{HTTP:Authorization} ^(.*)
-RewriteRule ^/roundup/roundup.cgi(.*) /home/httpd/html/roundup/roundup.cgi$1 [e=HTTP_CGI_AUTHORIZATION:%1,t=application/x-httpd-cgi,l]
-------8<------- snip here ------8<-------
- note: the RewriteRule must be on one line - no breaks
- 4. Re-start your apache to re-load the config
- 5. Load up the page "/roundup/roundup.cgi/"
-
+ 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