doc/admin_guide.txt

   1 ====================
   2 Administration Guide
   3 ====================
   4
   5 :Version: $Revision: 1.2 $
   6
   7 .. contents::
   8
   9 What does Roundup install?
  10 ==========================
  11
  12 There's two "installations" that we talk about when using Roundup:
  13
  14 1. The installation of the software and its support files. This uses the
  15    standard Python mechanism called "distutils" and thus Roundup's core code,
  16    executable scripts and support data files are installed in Python's
  17    directories. On Windows, this is typically:
  18
  19    Scripts
  20      <python dir>\scripts\...
  21    Core code
  22      <python dir>\lib\site-packages\roundup\...
  23    Support files
  24      <python dir>\share\roundup\...
  25
  26    and on Unix-like systems (eg. Linux):
  27
  28    Scripts
  29      <python root>/bin/...
  30    Core code
  31      <python root>/lib-<python version>/site-packages/roundup/...
  32    Support files
  33      <python root>/share/roundup/...
  34
  35 2. The installation of a specific tracker. When invoking the roundup-admin
  36    "inst" (and "init") commands, you're creating a new Roundup tracker. This
  37    installs configuration files, HTML templates, detector code and a new
  38    database. You have complete control over where this stuff goes through
  39    both choosing your "tracker home" and the DATABASE variable in
  40    config.py.
  41
  42
  43 Users and Security
  44 ==================
  45
  46 Roundup holds its own user database which primarily contains a username,
  47 password and email address for the user. Roundup *must* have its own user
  48 listing, in order to maintain internal consistency of its data. It is a
  49 relatively simple exercise to update this listing on a regular basis, or on
  50 demand, so that it matches an external listing (eg. unix passwd file, LDAP,
  51 etc.)
  52
  53 Roundup identifies users in a number of ways:
  54
  55 1. Through the web, users may be identified by either HTTP Basic
  56    Authentication or cookie authentication. If you are running the web
  57    server (roundup-server) through another HTTP server (eg. apache or IIS)
  58    then that server may require HTTP Basic Authentication, and it will pass
  59    the ``REMOTE_USER`` variable through to Roundup. If this variable is not
  60    present, then Roundup defaults to using its own cookie-based login
  61    mechanism.
  62 2. In email messages handled by roundup-mailgw, users are identified by the
  63    From address in the message.
  64
  65 In both cases, Roundup's behaviour when dealing with unknown users is
  66 controlled by Permissions defined in the "SECURITY SETTINGS" section of the
  67 tracker's ``dbinit.py`` module:
  68
  69 Web Registration
  70   If granted to the Anonymous Role, then anonymous users will be able to
  71   register through the web.
  72 Email Registration
  73   If granted to the Anonymous Role, then email messages from unknown users
  74   will result in those users being registered with the tracker.
  75
  76 More information about how to customise your tracker's security settings
  77 may be found in the `customisation documentation`_.
  78
  79 Tasks
  80 =====
  81
  82 Maintenance of Roundup can involve one of the following:
  83
  84 1. `tracker backup`_
  85 2. `software upgrade`_
  86 3. `migrating backends`_
  87 4. `moving a tracker`_
  88
  89
  90 Tracker Backup
  91 --------------
  92
  93 Stop the web and email frontends and to copy the contents of the tracker home
  94 directory to some other place using standard backup tools.
  95
  96
  97 Software Upgrade
  98 ----------------
  99
 100 Always make a backup of your tracker before upgrading software. Steps you may
 101 take:
 102
 103 1. ensure that the unit tests run on your system
 104 2. copy your tracker home to a new directory
 105 3. follow the steps in the upgrading documentation for the new version of
 106    the software
 107 4. test each of the admin tool, web interface and mail gateway using the new
 108    version of the software
 109 5. stop the production web and email frontends
 110 6. perform the upgrade steps on the existing tracker directory
 111 7. upgrade the software
 112 8. restart your tracker
 113
 114
 115 Migrating Backends
 116 ------------------
 117
 118 1. stop the existing tracker web and email frontends (preventing changes)
 119 2. use the roundup-admin tool "export" command to export the contents of
 120    your tracker to disk
 121 3. copy the tracker home to a new directory
 122 4. change the backend used in the tracker home ``select_db.py`` file
 123 5. delete the "db" directory from the new directory
 124 6. use the roundup-admin "import" command to import the previous export with
 125    the new tracker home
 126 7. test each of the admin tool, web interface and mail gateway using the new
 127    backend
 128 8. move the old tracker home out of the way (rename to "tracker.old") and
 129    move the new tracker home into its place
 130 9. restart web and email frontends
 131
 132
 133 Moving a Tracker
 134 ----------------
 135
 136 If you're moving the tracker to a similar machine, you should:
 137
 138 1. install Roundup on the new machine and test that it works there,
 139 2. stop the existing tracker web and email frontends (preventing changes),
 140 3. copy the tracker home directory over to the new machine, and
 141 4. start the tracker web and email frontends on the new machine.
 142
 143 Most of the backends are actually portable across platforms (ie. from Unix to
 144 Windows to Mac). If this isn't the case (ie. the tracker doesn't work when
 145 moved using the above steps) then you'll need to:
 146
 147 1. install Roundup on the new machine and test that it works there,
 148 2. stop the existing tracker web and email frontends (preventing changes),
 149 3. use the roundup-admin tool "export" command to export the contents of
 150    the existing tracker,
 151 4. copy the export to the new machine,
 152 5. use the roundup-admin "import" command to import the tracker on the new
 153    machine, and
 154 6. start the tracker web and email frontends on the new machine.
 155
 156
 157 -------------------
 158
 159 Back to `Table of Contents`_
 160
 161 .. _`Table of Contents`: index.html
 162 .. _`customisation documentation`: customizing.html
 163