![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/installation.txt b/doc/installation.txt
index 7607ba087d8e69665a78d832b0dbf801f2612cc0..4fada5d489336796a4c10cb32445f69bea7eda93 100644 (file)
--- a/doc/installation.txt
+++ b/doc/installation.txt
Installing Roundup
==================
-:Version: $Revision: 1.40 $
+:Version: $Revision: 1.73 $
.. 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/.
have to install the win32all package separately (get it from
http://starship.python.net/crew/mhammond/win32/).
+Non-Python2.3 users may need to `install the "CSV" module`_.
+
+Install the "CSV" module
+------------------------
+
+Note: CSV stands for Comma-Separated-Value. These files are used by all
+ manner of programs (eg. spreadsheets) to exchange data.
+
+The "CSV" module is required if you wish to import or export data in the
+tracker, or if you wish to use the online generic class editing facility.
+
+If you're using a version of Python older than 2.3, then you will need to
+install the "CSV" module from `Object Craft`_. Users of Python2.3 and later
+don't need to. If you have a C compiler installed, then download the source
+and follow their installation instructions (simply ``python setup.py
+install``.)
+
+If you're on Windows and don't have a C compiler, then you'll need to
+download the pre-compiled ``csv.pyd`` file and install it. To install, just
+copy it to your Python installation in the ``lib\site-packages`` directory.
+For Python 2.2, this would be::
+
+ c:\python22\lib\site-packages
+
+Once the CSV module is installed, you *must* restart roundup-server if it
+is already running, or the new module won't be detected.
+
+If you're on some other platform and don't have a C compiler, you'll need
+to ask for help on the roundup-users mailing list.
+
+.. _`Object Craft`: http://object-craft.com.au/
+
Getting Roundup
===============
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 `administration
+guide`_.
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,
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/'
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
``'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:
- http://locahost:8080/support/
+ http://localhost:8080/support/
and you should see the tracker interface.
The actual storage of Roundup tracker information is handled by backends.
There's several to choose from, each with benefits and limitations:
-**anydbm**
- This backend is guaranteed to work on any system that Python runs on. It
- will generally choose the best dbm backend that is available on your system
- (from the list dbhash, gdbm, dbm, dumbdbm). It is the least scaleable of all
- backends, but performs well enough for a smallish tracker (a couple of
- thousand issues, under fifty users, ...).
-**bsddb**
- This effectively the same as anydbm, but uses the bsddb backend. This allows
- it to gain some performance and scaling benefits.
-**bsddb3**
- Again, this effectively the same as anydbm, but uses the bsddb3 backend.
- This allows it to gain some performance and scaling benefits.
-**sqlite**
- This uses the SQLite_ embedded RDBMS to provide a fast, scaleable backend.
- There are no limitations, and it's much faster and more scaleable than the
- dbm backends.
+========== =========== ===== ==============================
+Name Speed Users Support
+========== =========== ===== ==============================
+anydbm Slowest Few Always available
+bsddb Slow Few Usually available
+sqlite Fastest(*) Few Needs install (SQLite_)
+metakit Fastest(*) Few Needs install (metakit_)
+postgresql Fast Many Needs install/admin (psycopg_)
+mysql Fast Many Needs install/admin (MySQLdb_)
+========== =========== ===== ==============================
+
+**sqlite** and **metakit**
+ These use the embedded database engines SQLite_ and metakit_ to provide
+ very fast backends. They are not suitable for trackers which will have
+ many simultaneous users.
+**postgresql**
+ Backend for popular RDBMS PostgreSQL. You must read doc/postgresql.txt for
+ additional installation steps and requirements.
**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.
-**metakit**
- This backend is implemented over the metakit_ storage system, using Mk4Py as
- the interface. It scales much better than the dbm backends.
+ Backend for popular RDBMS MySQL. You must read doc/mysql.txt for additional
+ installation steps and requirements.
-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
-instructions in the `maintenance documentation`_.
+You may defer your decision by setting your tracker up with the anydbm
+backend (which is guaranteed to be available) and switching to one of the
+other backends at any time using the instructions in the `administration
+guide`_.
Configure a Web Interface
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)::
+
+ 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:
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.
+As a regular job using an IMAP source
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Shared Environment Steps
-------------------------
+To retrieve from an IMAP mailbox, use a *cron* entry similar to the
+POP one::
+
+ 0,10,20,30,40,50 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support imap <imap_spec>
+
+where imap_spec is "``username:password@server``" that specifies the roundup
+submission user's IMAP account name, password and server. You may
+optionally include a mailbox to use other than the default ``INBOX`` with
+"``imap username:password@server mailbox``".
+
+If you have a secure (ie. HTTPS) IMAP server then you may use ``imaps``
+in place of ``imap`` in the command to use a secure connection.
+
+As with the POP job, on windows, you would set up the command using the
+windows scheduler.
+
+
+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
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
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
===========
-Read the separate `maintenance documentation`_ for information about how to
+Read the separate `administration guide`_ for information about how to
perform common maintenance tasks with Roundup.
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. See
+ the customisation example `adding a new field to the classic schema`_.
+2. Do you want to track internal software development issues and customer
+ support issues separately? You can just set up an additional "issue"
+ class called "cust_issues" in the same tracker, mimicing the normal
+ "issue" class, but with different properties. See the customisation
+ example `tracking different types of issues`_.
+
+
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 `UNIX environment steps`_.
+
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 `UNIX environment steps`_.
+
+
-------------------------------------------------------------------------------
Back to `Table of Contents`_
.. _`roundup specification`: spec.html
.. _`tracker configuration`: customizing.html#tracker-configuration
.. _`customisation documentation`: customizing.html
+.. _`Adding a new field to the classic schema`:
+ customizing.html#adding-a-new-field-to-the-classic-schema
+.. _`Tracking different types of issues`:
+ customizing.html#tracking-different-types-of-issues
.. _`customising roundup`: customizing.html
.. _`upgrading document`: upgrading.html
-.. _`maintenance documentation`: maintenance.html
+.. _`administration guide`: admin_guide.html
.. _sqlite: http://www.hwaci.com/sw/sqlite/
.. _metakit: http://www.equi4.com/metakit/
+.. _Psycopg: http://initd.org/software/initd/psycopg
+.. _MySQLdb: http://sourceforge.net/projects/mysql-python