
==================
roundup for Debian
==================

For upgrading your roundup data and templates from older roundup
versions, see /usr/share/doc/roundup/doc/upgrading.txt.gz.

The following documentation is adjusted to the Debian roundup
directory layout. More information on tracker installation
can be found at /usr/share/doc/roundup/doc/installation.txt.gz.

NOTE from your package maintainer: Installing as a CGI is not supported
  by the Debian package. If you really need that, you have to copy your
  files around manually. Please note that roundup's performance as a CGI
  sucks - better reverse-proxy to a stand-alone server, if you're after
  SSL and these options.


Caution: If you want to run roundup under the control of runit,
please link it into the service directory as 'roundup'.
Otherwise, automatic upgrades might fail.

The package makes some use of the jQuery library in the `devel' template.
To get this functionality, you need to install the libjs-jquery package.


0. Backend selection
====================

Note that when selecting back ends one has to consider the desired
performance. The `anydbm` module is the slowest and should only
be used for small demo trackers.
The best back ends with regard to performance, scaling up to several
thousand issues in the tracker DB, are the big database packages
PostgreSQL (installed with python-psycopg, backend `postgresql`) and
MySQL (installed with python-mysqldb, backend `mysql`).

The actual backend is selected by the contents of the file
`db/backend_name`, assuming default paths and the setting of
'database = db' in `config.ini`'s '[main]' section. For PostgreSQL,
the contents of this file would be `postgresql`.


1. System-wide tracker installation
===================================

a) Installation
   ------------

   The default system-wide tracker directory is /var/lib/roundup/trackers/.
   To install a new tracker `mytracker', issue as root:

   # roundup-admin install
   Enter tracker home: /var/lib/roundup/trackers/mytracker
   Templates: classic
   Select template [classic]: classic
   Back ends: anydbm, mysql, postgresql, metakit, sqlite
   Select backend [anydbm]: anydbm

   Then, edit /var/lib/roundup/trackers/mytracker/config.ini and adjust
   the values.

   IMPORTANT: Don't forget to initialise the tracker database with:
   # roundup-admin initialise

   IMPORTANT: Don't forget to chown the database directory (usually
   'db' in the tracker's home) to the roundup user, as roundup will
   otherwise not be able to write to the database, and hence bail out:
   # chown -R roundup /var/lib/roundup/trackers/your-tracker-home


b) I. Web gateway as standalone http server
   ----------------------------------------

   Edit /var/lib/roundup/trackers/mytracker/config.ini and set TRACKER_WEB
   to "http://localhost:8088/mytracker/".

   Since the server won't run as root, you must use a different user, eg.
   "www-data" (the Debian standard web server's user id), or "roundup",
   the user that this package creates for use by the roundup server.

   There are two major ways to run roundup, one as a service under
   'runit', the other as a standard daemon from an init.d script.

   The following examples are geared towards using the default user,
   roundup:

   # chown -R roundup:roundup /var/lib/roundup/trackers/mytracker

   Then run (as a first test):
   # su roundup -c 'roundup-server -p 8088 mytracker=/var/lib/roundup/trackers/mytracker'

   To use the roundup server together with `runit`, install the
   `runit` package and edit the file `/etc/roundup/service/run`.
   After that, add a symbolic link to enable the roundup server:
   # ln -s /etc/roundup/service /var/service/roundup

   The roundup server should start within 5 seconds, logging to
   `/var/log/roundup/current`.
   You can control the server with the `sv` command from the
   `runit` package, or the init script.

   An alternative way to daemonize the roundup-server is given using
   start-stop-daemon(8). See the example script located at
   `/usr/share/doc/roundup/examples/roundup.rc-debian`.

   You have the option of running the roundup server in standalone
   mode, or monitored under the `runit` package. To choose either
   option, you can edit the value of the `USERUNIT` variable in
   `/etc/default/roundup`. The default is to not use runit. The init
   script can still be used and will issue runit commands to the same
   effect as if running stand-alone.


   II. Web gateway as CGI script
   -----------------------------

   Note that this solution is somewhat slower then the standalone
   http server since every request is starting up a Python instance.

   Add the tracker to TRACKER_HOMES variable in /etc/roundup/cgiconf.py:
   TRACKER_HOMES = {
     'mytracker': '/var/lib/roundup/trackers/mytracker',
   }
   Or you can set an environment variable with Apache mod_env:
   <Directory "/usr/lib/cgi-lib">
     SetEnv TRACKER_HOMES mytracker=/var/lib/roundup/trackers/mytracker
   </Directory>

   IMPORTANT: under most web server configurations, cgi scripts are
   executed under a certain user. This user must have write access
   to the database directory and all files in it. All other tracker
   files must at least be readable by this user.
   For example apache runs roundup.cgi under user and group www-data,
   so you have to adjust the files like this:
   # chown -R www-data:www-data /var/lib/roundup/trackers/mytracker


   III. Web gateway with mod_python
   --------------------------------

   Using mod_python is much faster than a CGI script which loads a Python
   interpreter for every request. First install the Debian package
   `libapache2-mod-python` and enable the mod_python module.
   Then adjust the example apache config file located under
   /usr/share/doc/roundup/examples/roundup_apache and copy it into
   "/etc/apache2/conf.d/roundup".

   After reloading apache the tracker instance will be accessible
   under the URL "http://localhost/roundup/mytracker/".

c) Email gateway
   Define an email alias mytracker@localhost as a pipe to:
   |/usr/bin/roundup-mailgw /var/lib/roundup/trackers/mytracker

   If you are an Exim4 user, please refer to the upstream documentation file
   "installation.txt" and to the file /usr/share/doc/exim4/README.* files as
   well.


2. Private per-user tracker installation
========================================

a) Installation
   Each user can have their own trackers. Just replace the above
   pathnames with custom ones, for example /home/user/mytracker (in
   the following also referenced with $HOME/mytracker).

b) I. Web gateway as standalone http server
   ----------------------------------------

   Edit $HOME/mytracker/config.ini and set TRACKER_WEB
   to "http://localhost:8088/mytracker/".
   Then run (as a first test):
   $ roundup-server -p 8088 mytracker=/home/user/mytracker

   To install the roundup server properly, install the `runit` package and
   make a runsvdir directory:
   $ mkdir $HOME/service
   Then copy (with options -rL) the roundup service files into it:
   $ cp -rL /etc/roundup/service $HOME/service/roundup

   Edit the file `$HOME/service/roundup/run` to suit your needs.
   After that start the runit control program:
   $ runsvdir $HOME/service &

   The roundup server should start within 5 seconds, logging to
   `$HOME/service/roundup/log/main/current`.
   You can control the server with the `roundup-ctl` script, for example:
   $ roundup-ctl -d $HOME/service/roundup down

   To stop the runsvdir process cleanly send it a HUP signal with the
   kill(1) command.

   II. Web gateway as CGI script
   -----------------------------

   You can also use the system-wide installed web server, but
   remember as above that the roundup.cgi script is executed as a
   certain user and group which must have write access to the database.

   Copy /usr/share/doc/roundup/examples/roundup.cgi to your local cgi
   directory (usually $HOME/public_html/cgi-lib/) and make sure it is
   executable.
   Add the tracker home:
   TRACKER_HOMES = {
     'mytracker': '/home/user/mytracker',
   }

c) Mail gateway
   With qmail, a user can set up a mail gateway with:
   $ chmod +t $HOME
   $ echo "|/usr/bin/roundup-mailgw $HOME/mytracker" > \
     $HOME/.qmail-mytracker
   $ chmod -t $HOME


3. Long running roundup-server instances
========================================

Note that long running Python processes may deplete your system memory
since the current [1]C Python implementation never free()s allocated
memory.

[1] http://evanjones.ca/python-memory.html


For more information, including installing the Zope frontend (ZRoundup),
read /usr/share/doc/roundup/doc/installation.txt.gz.
