![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/installation.txt b/doc/installation.txt
index c2186c815b3f7c69c4124889148eca07069f1257..35b80c4ed0527f5f11614a05a8c684c47babc264 100644 (file)
--- a/doc/installation.txt
+++ b/doc/installation.txt
Installing Roundup
==================
-:Version: $Revision: 1.15 $
+: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 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
=============
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
-------------------
-Run ``python ./run_tests`` and make sure there
-are no errors. If there are errors, please let us know!
+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.
-Getting Roundup
-===============
-Download the latest version from http://roundup.sf.net/.
+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`_.
+Python -- see `testing your python`_. There's four steps to follow in your
+installation:
+
+1. `basic installation steps`_ that all installers must follow
+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.
+
+
+Basic Installation Steps
+------------------------
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
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::
+ 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 instance (necessary to do before you can
- use the software in any real fashion):
+ 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), you need to set up a "tracker
+ home":
- a. (Optional) If you intend to keep your roundup instances
+ 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/instances
+ 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``
+ 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)::
- 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
+ Enter tracker home: /opt/roundup/trackers/support
+ Templates: classic
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. Note that you may change any of the configuration
- after you've initialised the instance - it's just better to have valid
- values for this stuff now.
+ 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`_.
- 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 instance 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 instance has been created.
+ Once this is done, the tracker 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::
+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::
- support:*:1002:jblaine,samh,geezer,mail
+ roundup-server support=/opt/roundup/trackers/support
- 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::
+ then direct your web browser at:
- support:*:1002:jblaine,samh,geezer,mail,apache
+ http://locahost:8080/support/
-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.
+ and you should see the tracker interface.
-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::
+Choosing Your Template
+----------------------
- "|/opt/roundup/bin/roundup-mailgw /opt/roundup/instances/support"
+Classic Template
+~~~~~~~~~~~~~~~~
- If you use Sendmail's ``smrsh`` mechanism, please read the notes
- under 'Platform-Specific Notes'
+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.
- 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)::
+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
+---------------------
- 10 * * * * /opt/roundup/bin/roundup-mailgw
- /opt/roundup/instances/support /var/mail/support
+The actual storage of Roundup tracker information is handled by backends.
+There's several to choose from, each with benefits and limitations:
-6. TODO (mention perms)
+**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.
-7. Test the email gateway. Under most flavors of UNIX, this
- can be done by::
+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`_.
- echo test | mail -s '[issue] test' support@YOUR_DOMAIN_HERE
+Configure a Web Interface
+-------------------------
-Upgrading
-=========
+There are three web interfaces to choose from:
-Read the separate `upgrading document`_, which describes the steps needed to
-upgrade existing tracker instances for each version of Roundup that is
-released.
+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`_.
-ZRoundup
-========
-Install roundup as usual (see installation_).
+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 an INSTANCE_HOME/Products or the Zope
+your Products directory either in 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.
+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::
+
+ 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
+------------------------
+
+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
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
--------------
which points to the full path of your actual ``roundup-mailgw``
script.
-2. change your alias to ``"|roundup-mailgw <instance_home>"``
+2. change your alias to ``"|roundup-mailgw <tracker_home>"``
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/