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

:Version: $Revision: 1.10 $

.. 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 instances
 Instances consist of core support files, issues
 (be they bug reports or otherwise), instance configuration file(s),
 etc.  Roundup instances 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.


Extended Template
-----------------

The extended template adds additional information to issues: product,
platform, version, targetversion and supportcall.
There is an additional class for
handling support calls, which includes a time log, customername, rate and
source.

The priorty class has different default entries too: "fatal-bug", "bug",
"usability" and "feature".

Users of this template will want to change the contents of the product
class as soon as the instance is created.


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


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

Run ``"python ./run_tests"`` and make sure there
are no errors.  If there are errors, please let us know!

Note: if you're installing from the CVS, you will need to run "python setup.py
build" before the tests will work, as there are modules that must be
generated that are not stored in the CVS.


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

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


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

Set aside 15-30 minutes.

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``, use the ``--install-scripts`` option as follows,
   replacing ``/opt/roundup/bin`` with the location where you would like
   the scripts to reside::

       python setup.py install --install-scripts=/opt/roundup/bin

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

   a. (Optional) If you intend to keep your roundup instances
      under one top level directory which does not exist yet,
      you should create that directory now.  Example:

         mkdir /opt/roundup/instances

   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 instance home: /opt/roundup/instances/support
          Templates: classic, extended
          Select template [classic]: classic
          Back ends: anydbm, bsddb
          Select backend [anydbm]: anydbm

      You will now be directed to edit the instance configuration and
      initial schema. See `Customising Roundup`_ for details on configuration
      and schema changes.

   d.  ``roundup-admin initialise``

      This step initialises the instance database. You will need to supply
      an admin password at this step. You will be prompted:

          Admin Password:
                 Confirm:

      Once this is done, the instance has been created.

3. Each instance 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 instance name.  To this
   'support' group I then add all of the UNIX usernames who will be
   working with this Roundup instance.  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

4. Configure your new instance by editing the file ``instance_config.py``
   located in the instance home you specified in step 2c above.  This
   file is Python code and must adhere to Python syntax rules, but
   don't be daunted if you do not know Python - it should look pretty
   straightfoward if you carefully read the comments in the file.

5. There are two supported ways to get emailed issues into the
   Roundup instance.  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/instances/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/instances/support /var/mail/support

6. TODO (mention perms)

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

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

TODO (finish)

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 INSTANCE_HOME/Products or the Zope
code tree lib/python/Products.

You will need to create the instance 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 instance.


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