doc/maintenance.txt

   1 ============================
   2 Maintaining Roundup Trackers
   3 ============================
   4
   5 :Version: $Revision: 1.3 $
   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 *nix (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 Tasks
  44 =====
  45
  46 Maintenance of Roundup can involve one of the following:
  47
  48 1. `tracker backup`_
  49 2. `software upgrade`_
  50 3. `migrating backends`_
  51 3. `moving a tracker`_
  52
  53
  54 Tracker Backup
  55 --------------
  56
  57 Stop the web and email frontends and to copy the contents of the tracker home
  58 directory to some other place using standard backup tools.
  59
  60
  61 Software Upgrade
  62 ----------------
  63
  64 Always make a backup of your tracker before upgrading software. Steps you may
  65 take:
  66
  67 1. ensure that the unit tests run on your system
  68 2. copy your tracker home to a new directory
  69 3. follow the steps in the upgrading documentation for the new version of
  70    the software
  71 4. test each of the admin tool, web interface and mail gateway using the new
  72    version of the software
  73 5. stop the production web and email frontends
  74 6. perform the upgrade steps on the existing tracker directory
  75 7. upgrade the software
  76 8. restart your tracker
  77
  78
  79 Migrating Backends
  80 ------------------
  81
  82 1. stop the existing tracker web and email frontends (preventing changes)
  83 2. use the roundup-admin tool "export" command to export the contents of
  84    your tracker to disk
  85 3. copy the tracker home to a new directory
  86 4. change the backend used in the tracker home ``select_db.py`` file
  87 5. delete the "db" directory from the new directory
  88 6. use the roundup-admin "import" command to import the previous export with
  89    the new tracker home
  90 7. test each of the admin tool, web interface and mail gateway using the new
  91    backend
  92 8. move the old tracker home out of the way (rename to "tracker.old") and
  93    move the new tracker home into its place
  94 9. restart web and email frontends
  95
  96
  97 Moving a Tracker
  98 ----------------
  99
 100 If you're moving the tracker to a similar machine, you should:
 101
 102 1. install Roundup on the new machine and test that it works there,
 103 2. stop the existing tracker web and email frontends (preventing changes),
 104 3. copy the tracker home directory over to the new machine, and
 105 4. start the tracker web and email frontends on the new machine.
 106
 107 Most of the backends are actually portable across platforms (ie. from Unix to
 108 Windows to Mac). If this isn't the case (ie. the tracker doesn't work when
 109 moved using the above steps) then you'll need to:
 110
 111 1. install Roundup on the new machine and test that it works there,
 112 2. stop the existing tracker web and email frontends (preventing changes),
 113 3. use the roundup-admin tool "export" command to export the contents of
 114    the existing tracker,
 115 4. copy the export to the new machine,
 116 5. use the roundup-admin "import" command to import the tracker on the new
 117    machine, and
 118 6. start the tracker web and email frontends on the new machine.
 119
 120
 121 -------------------
 122
 123 Back to `Table of Contents`_
 124
 125 .. _`Table of Contents`: index.html
 126