![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/installation.txt b/doc/installation.txt
index b6eba99514d61d27d120b8c43ed90b6f79a8ea3c..35b80c4ed0527f5f11614a05a8c684c47babc264 100644 (file)
--- a/doc/installation.txt
+++ b/doc/installation.txt
Installing Roundup
==================
-:Version: $Revision: 1.39 $
+:Version: $Revision: 1.45 $
.. contents::
Roundup -- from installation and scripts.
+For The Really Impatient
+========================
+
+If you just want to give Roundup a whirl Right Now, then simply run
+``python setup.py demo``. This will set up a simple demo tracker on your
+machine. When it's done, it'll print out a URL to point your web browser
+at so you may start playing. Three users will be set up:
+
+1. anonymous - the "default" user with permission to do very little
+2. demo (password "demo") - a normal user who may create issues
+3. admin (password "admin") - an administrative user who has complete
+ access to the tracker
+
+
Installation
============
and modify the python path accordingly.
2. To create a Roundup tracker (necessary to do before you can
- use the software in any real fashion):
+ use the software in any real fashion), you need to set up a "tracker
+ home":
a. (Optional) If you intend to keep your roundup trackers
under one top level directory which does not exist yet,
Back ends: anydbm, bsddb
Select backend [anydbm]: anydbm
+ The "support" part of the tracker name can be anything you want - it
+ is going to be used as the directory that the tracker information
+ will be stored in.
+
You will now be directed to edit the tracker configuration and
initial schema. At a minimum, you must set ``MAILHOST``,
``TRACKER_WEB``, ``MAIL_DOMAIN`` and ``ADMIN_EMAIL``. Note that the
configuration file errors, then see the `tracker configuration`_ section
of the `customisation documentation`_.
- If you just want to get set up to test things quickly, you can even
- just set the TRACKER_WEB variable to::
+ If you just want to get set up to test things quickly (and follow
+ the instructions in step 3 below), you can even just set the
+ TRACKER_WEB variable to::
TRACKER_WEB = 'http://localhost:8080/support/'
new tracker out, assuming ``TRACKER_WEB`` is set to
``'http://localhost:8080/support/'``, run::
- roundup-server -p 8080 support=/opt/roundup/trackers/support
+ roundup-server support=/opt/roundup/trackers/support
then direct your web browser at:
**mysql**
Backend for popular RDBMS MySQL. This backend uses MySQL's Berkeley DB
(transaction safe) table format, so with small amount of data it may be a
- bit slower than *dbm backends (due to mysql layer's overhead). However with
+ bit slower than \*dbm backends (due to mysql layer's overhead). However with
lots of data mysql may perform better (due to query optimisation). No actual
serious benchmarks were made though. For more info on installation of this
backend see doc/mysql.txt.
**metakit**
This backend is implemented over the metakit_ storage system, using Mk4Py as
the interface. It scales much better than the dbm backends.
-**gadfly**
- This is a proof-of-concept relational database backend, not really intended
- for actual production use, although it can be. It uses the Gadfly RDBMS
- to store data. It is unable to perform string searches due to gadfly not
- having a LIKE operation. It should scale well, assuming a client/server
- setup is used. It's much slower than even the dbm backends.
Note: you may set your tracker up with the anydbm backend (which is guaranteed
to be available) and switch to one of the other backends at any time using the
3. `Zope product - ZRoundup`_
You may need to give the web server user permission to access the tracker home
-- see the `shared environment steps`_ for information.
+- see the `shared environment steps`_ for information. You may also need to
+configure your system in some way - see `platform-specific notes`_.
Web Server cgi-bin
restrict access to your tracker to only use HTTPS. Access will be slower
than through the `stand-alone web server`_ though.
+If you're using IIS on a Windows platform, you'll need to run this command
+for the cgi to work (it turns on the PATH_INFO cgi variable)::
+
+ adsutil.vbs set w3svc/AllowPathInfoForScriptMappings TRUE
+
+The ``adsutil.vbs`` file can be found in either ``c:\inetpub\adminscripts``
+or ``c:\winnt\system32\inetsrv\adminsamples\`` or
+``c:\winnt\system32\inetsrv\adminscripts\`` depending on your installation.
+
Copy the ``cgi-bin/roundup.cgi`` file to your web server's ``cgi-bin``
directory. You will need to configure it to tell it where your tracker home
is. You can do this either:
If you don't want to use the email component of Roundup, then remove the
"``nosyreaction.py``" module from your tracker "``detectors``" directory.
+See `platform-specific notes`_ for steps that may be needed on your system.
+
There are three supported ways to get emailed issues into the
Roundup tracker. You should pick ONE of the following, all
of which will continue my example setup from above:
working with this Roundup tracker. In addition to 'real' users,
the Roundup email gateway will need to have permissions to this
area as well, so add the user your mail service runs as to the
-group. The UNIX group might then look like::
+group (typically "mail" or "daemon"). The UNIX group might then
+look like::
support:*:1002:jblaine,samh,geezer,mail
like implementation details, you should read `Customising Roundup`_.
+Running Multiple Trackers
+=========================
+
+Things to think about before you jump off the deep end and install
+multiple trackers, which involve additional URLs, user databases, email
+addresses, databases to back up, etc.
+
+1. Do you want a tracker per product you sell/support? You can just add
+ a new property to your issues called Product, and filter by that.
+2. Do you want to track internal software development issues and customer
+ support issues separately? You can just set up an additiona "issue"
+ class called "cust_issues" in the same tracker, mimicing the normal
+ "issue" class, but with different properties.
+
+
Platform-Specific Notes
=======================
+Windows
+-------
+
+To have the Roundup web server start up when your machine boots up, set the
+following up in Scheduled Tasks (note, the following is for a cygwin setup):
+
+Run
+ ``c:\cygwin\bin\bash.exe -c "roundup-server TheProject=/opt/roundup/trackers/support"``
+Start In
+ ``C:\cygwin\opt\roundup\bin``
+Schedule
+ At System Startup
+
+To have the Roundup mail gateway run periodically to poll a POP email address,
+set the following up in Scheduled Tasks:
+Run
+ ``c:\cygwin\bin\bash.exe -c "roundup-mailgw /opt/roundup/trackers/support pop roundup:roundup@mail-server"``
+Start In
+ ``C:\cygwin\opt\roundup\bin``
+Schedule
+ Every 10 minutes from 5:00AM for 24 hours every day
+ Stop the task if it runs for 8 minutes
+
+
Sendmail smrsh
--------------
Linux
-----
+Make sure you read the instructions under `shared environment setup`_.
+
Python 2.1.1 as shipped with SuSE7.3 might be missing module
``_weakref``.
+
+Solaris
+-------
+
+You'll need to build Python.
+
+Make sure you read the instructions under `shared environment setup`_.
+
-------------------------------------------------------------------------------
Back to `Table of Contents`_