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

:Version: $Revision: 1.24 $

.. contents::


Overview
========

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

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.

Roundup trackers
 Trackers consist of core support files, issues
 (be they bug reports or otherwise), tracker configuration file(s),
 etc.  Roundup trackers also adhere to a specific "Template" which
 defines the fields usable/assignable on a per-issue basis.  A
 description of the provided templates follows.

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.


Backends
--------

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.
**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.
**metakit**
  This backend is implemented over the metakit storage system, using Mk4Py as
  the interface. It scales much better than the *dbm backends, but has some
  missing features:

  - you may not unset properties once they are set
  - journal retrieval is not implemented 


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.

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


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`` 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`` for ``python`` in all further commands you use in relation to
Roundup -- from installation and scripts.


Installation
============

Set aside 15-30 minutes. Please make sure you're using a supported version of
Python -- see `testing your python`_. There's three sections to this
installation guide:

1. `basic installation steps`_ that all installers must follow
2. `shared environment steps`_ to take if you're installing on a shared
    UNIX machine and want to restrict local access to roundup
3. `internet setup`_ steps to take if your tracker is to be used by the wider
    internet community

Most users will only need to follow the first step, since the environment will
be a trusted one.


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

1. To install the Roundup support code into your Python tree and
   Roundup scripts into /usr/local/bin::

       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

2. To create a Roundup tracker (necessary to do before you can
   use the software in any real fashion):

   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.  ``roundup-admin install``

      You will be asked a series of questions.  A description of
      the Roundup-provided templates can be found under the Overview_::

          Enter tracker home: /opt/roundup/trackers/support
          Templates: classic, extended
          Select template [classic]: classic
          Back ends: anydbm, bsddb
          Select backend [anydbm]: anydbm

      You will now be directed to edit the tracker configuration and
      initial schema. 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.  ``roundup-admin initialise``

      This step initialises the tracker database. 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.

3. XXX Set up the CGI interface

4. XXX Set up the mail gateway


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

Internet Setup
--------------

1. There are two supported ways to get emailed issues into the
   Roundup tracker.  You should pick ONE of the following, both
   of which will continue my example setup from above:

   a. Set up a mail alias called "support" as::

       "|/opt/roundup/bin/roundup-mailgw /opt/roundup/trackers/support"

      If you use Sendmail's ``smrsh`` mechanism, please read the notes
      under 'Platform-Specific Notes'

   b. OR... Configure roundup-mailgw to run every 10 minutes or
      so via ``cron``.  My cron job would be (these 2 lines all on one
      line)::

       10 * * * * /opt/roundup/bin/roundup-mailgw
                /opt/roundup/trackers/support /var/mail/support

   If you don't want to use the email component of Roundup, then remove the
   "``nosyreator.py``" module from your tracker "``detectors``" directory.

2. Test the email gateway.  Under most flavors of UNIX, this
   can be done by::

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

XXX mention HTTPS
XXX mention Basic vs. cookie auth


Upgrading
=========

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


ZRoundup
========

Install roundup as usual (see installation_).

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

You will need to create the tracker using the roundup-admin tool (step 2 in
installation_).

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


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


Platform-Specific Notes
=======================

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

Python 2.1.1 as shipped with SuSE7.3 might be missing module
``_weakref``.

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

Back to `Table of Contents`_

Next: `Getting Started`_

.. _`table of contents`: index.html
.. _`getting started`: getting_started.html
.. _`roundup specification`: spec.html
.. _`customising roundup`: customizing.html
.. _`upgrading document`: upgrading.html