![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/installation.txt b/doc/installation.txt
index 64e16d6ba76f8979b140996eee988392811fd1d7..7c0741c060b920d608386e5d5da6cf74283f1f53 100644 (file)
--- a/doc/installation.txt
+++ b/doc/installation.txt
Installing Roundup
==================
-:Version: $Revision: 1.44 $
+:Version: $Revision: 1.67 $
.. contents::
Prerequisites
=============
-Python 2.1.1 or newer with a functioning anydbm or bsddb module. Download the
-latest version from http://www.python.org/. It is highly recommended that
-users install the latest patch version of python - 2.1.3 or 2.2.1 - as these
-contain many fixes to serious bugs.
+Roundup requires Python 2.1.3 or newer with a functioning anydbm or
+bsddb module. Download the latest version from http://www.python.org/.
+It is highly recommended that users install the latest patch version
+of python as these contain many fixes to serious bugs.
If you want to use Berkeley DB bsddb3 with Roundup, use version 3.3.0 or
later. Download the latest version from http://pybsddb.sourceforge.net/.
Testing your Python
-------------------
-Once you've unpacked roundup's source, run ``python ./run_tests`` in the
-source directory and make sure there are no errors.
-If there are errors, please let us know!
+Once you've unpacked roundup's source, run ``python run_tests.py`` in the
+source directory and make sure there are no errors. If there are errors,
+please let us know!
If the above fails, you may be using the wrong version of python. Try
-``python2 ./run_tests``. If that works, you will need to substitute
+``python2 run_tests.py``. If that works, you will need to substitute
``python2`` for ``python`` in all further commands you use in relation to
Roundup -- from installation and scripts.
+For The Really Impatient
+========================
+
+If you just want to give Roundup a whirl Right Now, then simply run
+``python demo.py``. 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
============
+:Note: Some systems, such as Debian and NetBSD, already have Roundup
+ installed. Try running the command "roundup-admin" with no arguments,
+ and if it runs you may skip the `Basic Installation Steps`_
+ below and go straight to `configuring your first tracker`_.
+
Set aside 15-30 minutes. Please make sure you're using a supported version of
-Python -- see `testing your python`_. There's four steps to follow in your
+Python -- see `testing your python`_. There's several steps to follow in your
installation:
-1. `basic installation steps`_ that all installers must follow
-2. then optionally `configure a web interface`_
-3. and optionally `configure an email interface`_
-4. `shared environment steps`_ to take if you're installing on a shared
+1. `basic installation steps`_ if Roundup is not installed on your system
+2. `configuring your first tracker`_ that all installers must follow
+3. then optionally `configure a web interface`_
+4. and optionally `configure an email interface`_
+5. `UNIX environment steps`_ to take if you're installing on a shared
UNIX machine and want to restrict local access to roundup
+6. `additional language codecs`_
-Most users will only need to follow the first step, since the environment will
-be a trusted one.
+For information about how Roundup installs, see the `maintenance
+documentation`_.
Basic Installation Steps
------------------------
-1. To install the Roundup support code into your Python tree and
- Roundup scripts into /usr/local/bin (substitute that path for whatever is
- appropriate on your system). You need to have write permissions
- for these locations, eg. being root on unix::
+To install the Roundup support code into your Python tree and
+Roundup scripts into /usr/local/bin (substitute that path for whatever is
+appropriate on your system). You need to have write permissions
+for these locations, eg. being root on unix::
- python setup.py install
+ python setup.py install
- If you would like to place the Roundup scripts in a directory other
- than ``/usr/local/bin``, then specify the preferred location with
- ``--install-script``. For example, to install them in
- ``/opt/roundup/bin``::
+If you would like to place the Roundup scripts in a directory other
+than ``/usr/local/bin``, then specify the preferred location with
+``--install-script``. For example, to install them in
+``/opt/roundup/bin``::
- python setup.py install --install-scripts=/opt/roundup/bin
+ python setup.py install --install-scripts=/opt/roundup/bin
- You can also use the ``--prefix`` option to use a completely different
- base directory, if you do not want to use administrator rights. If you
- choose to do this, take note of the message at the end of installation
- and modify the python path accordingly.
+You can also use the ``--prefix`` option to use a completely different
+base directory, if you do not want to use administrator rights. If you
+choose to do this, take note of the message at the end of 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):
+
+Configuring your first tracker
+------------------------------
+
+1. To create a Roundup tracker (necessary to do before you can
+ 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,
Once this is done, the tracker has been created.
-3. At this point, your tracker is set up, but doesn't have a nice user
+2. At this point, your tracker is set up, but doesn't have a nice user
interface. To set that up, we need to `configure a web interface`_ and
optionally `configure an email interface`_. If you want to try your
new tracker out, assuming ``TRACKER_WEB`` is set to
then direct your web browser at:
- http://locahost:8080/support/
+ http://localhost:8080/support/
and you should see the tracker interface.
There are no limitations, and it's much faster and more scaleable than the
dbm backends.
**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
- 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.
+ Backend for popular RDBMS MySQL. According to benchmarks, this backend works
+ much faster than any of \*dbm ones, but slightly slower than metakit and
+ sqlite. You must read doc/mysql.txt for additional installation steps and
+ requirements.
+**postgresql**
+ Backend for popular RDBMS PostgreSQL. According to benchmarks, this
+ backend works much faster than any of \*dbm ones and mysql, but slightly
+ slower than metakit and sqlite. You must read doc/postgresql.txt for
+ additional installation steps and requirements.
**metakit**
This backend is implemented over the metakit_ storage system, using Mk4Py as
the interface. It scales much better than 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
+You should be wary of using all but the mysql backend with high-volume trackers
+(requests every second or two) as database locking is done on the whole
+database.
+
+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
instructions in the `maintenance documentation`_.
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 `UNIX 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.
+Note that if your Python isn't install as "python" then you'll need to edit
+the ``roundup.cgi`` script to fix the first line.
+
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)::
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:
Set ``roundup-mailgw`` up to run every 10 minutes or so. For example::
- 10 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support mailbox <mail_spool_file>
+ 0,10,20,30,40,50 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support mailbox <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"
As a regular job using a POP source
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To retrieve from a POP mailbox, use a *cron* entry to the mailbox one::
+To retrieve from a POP mailbox, use a *cron* entry similar to the mailbox one::
- 10 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support pop <pop_spec>
+ 0,10,20,30,40,50 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support pop <pop_spec>
where pop_spec is "``username:password@server``" that specifies the roundup
submission user's POP account name, password and server.
On windows, you would set up the command using the windows scheduler.
-Shared Environment Steps
-------------------------
+UNIX Environment Steps
+----------------------
Each tracker ideally should have its own UNIX group, so create
a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
may actually login and play with the roundup setup.
+Additional Language Codecs
+--------------------------
+
+If you intend to send messages to Roundup that use Chinese, Japanese or
+Korean encodings the you'll need to obtain CJKCodecs from
+http://cjkpython.berlios.de/
+
+
Maintenance
===========
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 command-line tools
+--------------------------
+
+To make the command-line tools accessible in Windows, you need to update
+the "Path" environment variable in the Registry via a dialog box.
+
+On Windows 2000 and later:
+
+1) Press the "Start" button.
+2) Choose "Settings"
+3) Choose "Control Panel"
+4) Choose "System"
+5) Choose "Advanced"
+6) Choose "Environmental Variables"
+7) Add: "<dir>\Scripts" to the "Path" environmental variable.
+
+Where <dir> in 7) is the root directory (e.g., ``C:\Python22\Scripts``)
+of your Python installation.
+
+I understand that in XP, 2) above is not needed as "Control
+Panel" is directly accessible from "Start".
+
+I do not believe this is possible to do in previous versions of Windows.
+
+
+Windows Server
+--------------
+
+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`_.
+Make sure you read the instructions under `UNIX environment steps`_.
Python 2.1.1 as shipped with SuSE7.3 might be missing module
``_weakref``.
You'll need to build Python.
-Make sure you read the instructions under `shared environment setup`_.
+Make sure you read the instructions under `UNIX environment steps`_.
+
-------------------------------------------------------------------------------