![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/installation.txt b/doc/installation.txt
index 703ed22abc8ae3195bb2d6e3643110518be894b2..35b80c4ed0527f5f11614a05a8c684c47babc264 100644 (file)
--- a/doc/installation.txt
+++ b/doc/installation.txt
Installing Roundup
==================
-:Version: $Revision: 1.25 $
+:Version: $Revision: 1.45 $
.. contents::
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
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, and it's much faster and more scaleable than the
- dbm backends.
-**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
-
-
-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`_.
Prerequisites
=============
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
===============
Roundup -- from installation and scripts.
+For The Really Impatient
+========================
+
+If you just want to give Roundup a whirl Right Now, then simply run
+``python setup.py demo``. 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
============
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:
+Python -- see `testing your python`_. There's four steps to follow in your
+installation:
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
+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
+ UNIX machine and want to restrict local access to roundup
Most users will only need to follow the first step, since the environment will
be a trusted one.
------------------------
1. To install the Roundup support code into your Python tree and
- Roundup scripts into /usr/local/bin::
+ 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 --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.
+
2. To create a Roundup tracker (necessary to do before you can
- use the software in any real fashion):
+ 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:
+ you should create that directory now. Example::
mkdir /opt/roundup/trackers
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_::
+ 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, extended
+ 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. 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.
+ 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`_.
- d. ``roundup-admin initialise``
+ 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::
- This step initialises the tracker database. You will need to supply
- an admin password at this step. You will be prompted::
+ 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.
-3. XXX Set up the CGI interface
+3. 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://locahost: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. 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.
+
+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`_.
+
+
+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.
+
+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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-4. XXX Set up the mail gateway
+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>
+
+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 to the mailbox one::
+
+ 10 * * * * /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
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
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'
+Maintenance
+===========
- 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
+Read the separate `maintenance documentation`_ for information about how to
+perform common maintenance tasks with Roundup.
Upgrading
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
===============
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
+-------
+
+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 `shared environment setup`_.
+
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 setup`_.
+
-------------------------------------------------------------------------------
Back to `Table of Contents`_
-Next: `Getting Started`_
+Next: `User Guide`_
.. _`table of contents`: index.html
-.. _`getting started`: getting_started.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/