--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/admin_guide.txt	Wed Feb 11 00:41:33 2004 +0000
@@ -0,0 +1,163 @@
+====================
+Administration Guide
+====================
+
+:Version: $Revision: 1.1 $
+
+.. contents::
+
+What does Roundup install?
+==========================
+
+There's two "installations" that we talk about when using Roundup:
+
+1. The installation of the software and its support files. This uses the
+   standard Python mechanism called "distutils" and thus Roundup's core code,
+   executable scripts and support data files are installed in Python's
+   directories. On Windows, this is typically:
+
+   Scripts
+     <python dir>\scripts\...
+   Core code
+     <python dir>\lib\site-packages\roundup\...
+   Support files
+     <python dir>\share\roundup\...
+
+   and on *nix (eg. Linux):
+
+   Scripts
+     <python root>/bin/...
+   Core code
+     <python root>/lib-<python version>/site-packages/roundup/...
+   Support files
+     <python root>/share/roundup/...
+
+2. The installation of a specific tracker. When invoking the roundup-admin
+   "inst" (and "init") commands, you're creating a new Roundup tracker. This
+   installs configuration files, HTML templates, detector code and a new
+   database. You have complete control over where this stuff goes through
+   both choosing your "tracker home" and the DATABASE variable in
+   config.py.
+
+
+Users and Security
+==================
+
+Roundup holds its own user database which primarily contains a username,
+password and email address for the user. Roundup *must* have its own user
+listing, in order to maintain internal consistency of its data. It is a
+relatively simple exercise to update this listing on a regular basis, or on
+demand, so that it matches an external listing (eg. unix passwd file, LDAP,
+etc.)
+
+Roundup identifies users in a number of ways:
+
+1. Through the web, users may be identified by either HTTP Basic
+   Authentication or cookie authentication. If you are running the web
+   server (roundup-server) through another HTTP server (eg. apache or IIS)
+   then that server may require HTTP Basic Authentication, and it will pass
+   the ``REMOTE_USER`` variable through to Roundup. If this variable is not
+   present, then Roundup defaults to using its own cookie-based login
+   mechanism.
+2. In email messages handled by roundup-mailgw, users are identified by the
+   From address in the message.
+
+In both cases, Roundup's behaviour when dealing with unknown users is
+controlled by Permissions defined in the "SECURITY SETTINGS" section of the
+tracker's ``dbinit.py`` module:
+
+Web Registration
+  If granted to the Anonymous Role, then anonymous users will be able to
+  register through the web.
+Email Registration
+  If granted to the Anonymous Role, then email messages from unknown users
+  will result in those users being registered with the tracker.
+
+More information about how to customise your tracker's security settings
+may be found in the `customisation documentation`_.
+
+Tasks
+=====
+
+Maintenance of Roundup can involve one of the following:
+
+1. `tracker backup`_ 
+2. `software upgrade`_
+3. `migrating backends`_
+3. `moving a tracker`_
+
+
+Tracker Backup
+--------------
+
+Stop the web and email frontends and to copy the contents of the tracker home
+directory to some other place using standard backup tools.
+
+
+Software Upgrade
+----------------
+
+Always make a backup of your tracker before upgrading software. Steps you may
+take:
+
+1. ensure that the unit tests run on your system
+2. copy your tracker home to a new directory
+3. follow the steps in the upgrading documentation for the new version of
+   the software
+4. test each of the admin tool, web interface and mail gateway using the new
+   version of the software
+5. stop the production web and email frontends
+6. perform the upgrade steps on the existing tracker directory
+7. upgrade the software
+8. restart your tracker
+
+
+Migrating Backends
+------------------
+
+1. stop the existing tracker web and email frontends (preventing changes)
+2. use the roundup-admin tool "export" command to export the contents of
+   your tracker to disk
+3. copy the tracker home to a new directory
+4. change the backend used in the tracker home ``select_db.py`` file
+5. delete the "db" directory from the new directory
+6. use the roundup-admin "import" command to import the previous export with
+   the new tracker home
+7. test each of the admin tool, web interface and mail gateway using the new
+   backend
+8. move the old tracker home out of the way (rename to "tracker.old") and 
+   move the new tracker home into its place
+9. restart web and email frontends
+
+
+Moving a Tracker
+----------------
+
+If you're moving the tracker to a similar machine, you should:
+
+1. install Roundup on the new machine and test that it works there,
+2. stop the existing tracker web and email frontends (preventing changes),
+3. copy the tracker home directory over to the new machine, and
+4. start the tracker web and email frontends on the new machine.
+
+Most of the backends are actually portable across platforms (ie. from Unix to
+Windows to Mac). If this isn't the case (ie. the tracker doesn't work when
+moved using the above steps) then you'll need to:
+
+1. install Roundup on the new machine and test that it works there,
+2. stop the existing tracker web and email frontends (preventing changes),
+3. use the roundup-admin tool "export" command to export the contents of
+   the existing tracker,
+4. copy the export to the new machine,
+5. use the roundup-admin "import" command to import the tracker on the new
+   machine, and
+6. start the tracker web and email frontends on the new machine.
+
+
+-------------------
+
+Back to `Table of Contents`_
+
+.. _`Table of Contents`: index.html
+.. _`customisation documentation`: customizing.html
+