clarified minimum version required for MySQL backend (4.0.16)

[roundup.git] / doc / installation.txt

==================
Installing Roundup
==================

:Version: $Revision: 1.65 $

.. contents::


Overview
========

Broken out separately, there are several conceptual pieces to a
Roundup installation:

Roundup trackers
 Trackers consist of issues (be they bug reports or otherwise), tracker
 configuration file(s), web HTML files etc. Roundup trackers are initialised
 with a "Template" which defines the fields usable/assignable on a
 per-issue basis.  Descriptions of the provided templates are given in
 `choosing your template`_.

Roundup support code
 Installed into your Python install's lib directory

Roundup scripts
 These include the email gateway, the roundup
 HTTP server, the roundup administration command-line interface, etc.


Prerequisites
=============

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 - 2.1.3, 2.2.3 or 2.3.2 -
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/.

If you're on windows, you will either need to be using the ActiveState python
distribution (at http://www.activestate.com/Products/ActivePython/), or you'll
have to install the win32all package separately (get it from
http://starship.python.net/crew/mhammond/win32/).


Getting Roundup
===============

Download the latest version from http://roundup.sf.net/.

Testing your Python
-------------------

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.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 several steps to follow in your
installation:

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. `shared environment steps`_ to take if you're installing on a shared
   UNIX machine and want to restrict local access to roundup


Basic Installation Steps
------------------------

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

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

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.


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,
      you should create that directory now.  Example::

         mkdir /opt/roundup/trackers

   b. Either add the Roundup script location to your ``PATH``
      environment variable or specify the full path to
      the command in the next step.

   c. Install a new tracker with the command ``roundup-admin install``.
      You will be asked a series of questions.  Descriptions of the provided
      templates can be found in `choosing your template`_ below.  Descriptions
      of the available backends can be found in `choosing your backend`_
      below.  The questions will be something like (you may have more
      templates or backends available)::

          Enter tracker home: /opt/roundup/trackers/support
          Templates: classic
          Select template [classic]: classic
          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 uses Python syntax, so almost every value must be
      ``'quoted'`` using single or double quotes. If you get stuck, and get
      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 (and follow
      the instructions in step 3 below), you can even just set the
      TRACKER_WEB variable to::

         TRACKER_WEB = 'http://localhost:8080/support/'

      The URL *must* end in a '/', or your web interface *will not work*.
      See `Customising Roundup`_ for details on configuration and schema
      changes. Note that you may change any of the configuration after
      you've initialised the tracker - it's just better to have valid values
      for this stuff now.

   d. Initialise the tracker database with ``roundup-admin initialise``.
      You will need to supply an admin password at this step. You will be
      prompted::

          Admin Password:
                 Confirm:

      Once this is done, the tracker has been created.

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 support=/opt/roundup/trackers/support

   then direct your web browser at:

     http://localhost:8080/support/

   and you should see the tracker interface.


Choosing Your Template
----------------------

Classic Template
~~~~~~~~~~~~~~~~

The classic template is the one defined in the `Roundup Specification`_. It
holds issues which have priorities and statuses. Each issue may also have a
set of messages which are disseminated to the issue's list of nosy users.

Minimal Template
~~~~~~~~~~~~~~~~

The minimal template has the minimum setup required for a tracker
installation. That is, it has the configuration files, defines a user database
and the basic HTML interface to that. It's a completely clean slate for you to
create your tracker on.


Choosing Your Backend
---------------------

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.
**mysql**
  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.

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`_.


Configure a Web Interface
-------------------------

There are three web interfaces to choose from:

1. `web server cgi-bin`_
2. `stand-alone web server`_
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. You may also need to
configure your system in some way - see `platform-specific notes`_.


Web Server cgi-bin
~~~~~~~~~~~~~~~~~~

A benefit of using the cgi-bin approach is that it's the easiest way to
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:

through an environment variable
 set the variable TRACKER_HOMES to be a colon (":") separated list of
 name=home pairs (if you're using apache, the SetEnv directive can do this)
directly in the ``roundup.cgi`` file itself
 add your instance to the TRACKER_HOMES variable as ``'name': 'home'``

The "name" part of the configuration will appear in the URL and identifies the
tracker (so you may have more than one tracker per cgi-bin script). Make sure
there are no spaces or other illegal characters in it (to be safe, stick to
letters and numbers). The "name" forms part of the URL that appears in the
tracker config TRACKER_WEB variable, so make sure they match. The "home"
part of the configuration is the tracker home directory.

Stand-alone Web Server
~~~~~~~~~~~~~~~~~~~~~~

This approach will give you the fastest of the three web interfaces. You may
investigate using ProxyPass or similar configuration in apache to have your
tracker accessed through the same URL as other systems.

The stand-alone web server is started with the command ``roundup-server``. It
has several options - display them with ``roundup-server -h``.

The tracker home configuration is similar to the cgi-bin - you may either edit
the script to change the TRACKER_HOMES variable or you may supply the
name=home values on the command-line after all the other options.

To make the server run in the background, use the "-d" option, specifying the
name of a file to write the server process id (pid) to.


Zope Product - ZRoundup
~~~~~~~~~~~~~~~~~~~~~~~

ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
your Products directory either in INSTANCE_HOME/Products or the Zope
code tree lib/python/Products.

When you next (re)start up Zope, you will be able to add a ZRoundup object
that interfaces to your new tracker.


Configure an Email Interface
----------------------------

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:

As a mail alias pipe process 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Set up a mail alias called "issue_tracker" as (include the quote marks):
"``|/usr/bin/python /usr/local/bin/roundup-mailgw <tracker_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/roundup-mailgw`` to "``/usr/local/bin/roundup-mailgw``" and change
the command to::

    |roundup-mailgw /opt/roundup/trackers/support
 
To test the mail gateway on unix systems, try::

    echo test |mail -s '[issue] test' support@YOUR_DOMAIN_HERE

As a regular job using a mailbox source
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Set ``roundup-mailgw`` up to run every 10 minutes or so. For example::

  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"
will be "``/var/mail/issue_tracker``".

As a regular job using a POP source
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To retrieve from a POP mailbox, use a *cron* entry similar to the mailbox one::

  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
------------------------

Each tracker ideally should have its own UNIX group, so create
a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
you're using NIS).  To continue with my examples so far, I would
create the UNIX group 'support', although the name of the UNIX
group does not have to be the same as the tracker name.  To this
'support' group I then add all of the UNIX usernames who will be
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 (typically "mail" or "daemon").  The UNIX group might then
look like::

     support:*:1002:jblaine,samh,geezer,mail

If you intend to use the web interface (as most people do), you
should also add the username your web server runs as to the group.
My group now looks like this::

     support:*:1002:jblaine,samh,geezer,mail,apache

The tracker "db" directory should be chmod'ed g+sw so that the group can
write to the database, and any new files created in the database will be owned
by the group.

An alternative to the above is to create a new user who has the sole
responsibility of running roundup. This user:

1. runs the CGI interface daemon
2. runs regular polls for email
3. runs regular checks (using cron) to ensure the daemon is up
4. optionally has no login password so that nobody but the "root" user
   may actually login and play with the roundup setup.


Maintenance
===========

Read the separate `maintenance documentation`_ for information about how to
perform common maintenance tasks with Roundup.


Upgrading
=========

Read the separate `upgrading document`_, which describes the steps needed to
upgrade existing tracker trackers for each version of Roundup that is
released.


Further Reading
===============

If you intend to use Roundup with anything other than the defualt
templates, if you would like to hack on Roundup, or if you would
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
--------------

If you use Sendmail's ``smrsh`` mechanism, you will need to tell
smrsh that roundup-mailgw is a valid/trusted mail handler
before it will work.

This is usually done via the following 2 steps:

1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
   which points to the full path of your actual ``roundup-mailgw``
   script.

2. change your alias to ``"|roundup-mailgw <tracker_home>"``


Linux
-----

Make sure you read the instructions under `shared 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 `shared environment steps`_.

-------------------------------------------------------------------------------

Back to `Table of Contents`_

Next: `User Guide`_

.. _`table of contents`: index.html
.. _`user guide`: user_guide.html
.. _`roundup specification`: spec.html
.. _`tracker configuration`: customizing.html#tracker-configuration
.. _`customisation documentation`: customizing.html
.. _`customising roundup`: customizing.html
.. _`upgrading document`: upgrading.html
.. _`maintenance documentation`: maintenance.html
.. _sqlite: http://www.hwaci.com/sw/sqlite/
.. _metakit: http://www.equi4.com/metakit/