1 ====================
2 Administration Guide
3 ====================
5 :Version: $Revision: 1.3 $
7 .. contents::
9 What does Roundup install?
10 ==========================
12 There's two "installations" that we talk about when using Roundup:
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:
19 Scripts
20 ``<python dir>\scripts\...``
21 Core code
22 ``<python dir>\lib\site-packages\roundup\...``
23 Support files
24 ``<python dir>\share\roundup\...``
26 and on Unix-like systems (eg. Linux):
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/...``
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.
43 Users and Security
44 ==================
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.)
53 Roundup identifies users in a number of ways:
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.
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:
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.
76 More information about how to customise your tracker's security settings
77 may be found in the `customisation documentation`_.
79 Tasks
80 =====
82 Maintenance of Roundup can involve one of the following:
84 1. `tracker backup`_
85 2. `software upgrade`_
86 3. `migrating backends`_
87 4. `moving a tracker`_
90 Tracker Backup
91 --------------
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.
97 Software Upgrade
98 ----------------
100 Always make a backup of your tracker before upgrading software. Steps you may
101 take:
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
115 Migrating Backends
116 ------------------
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
133 Moving a Tracker
134 ----------------
136 If you're moving the tracker to a similar machine, you should:
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.
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:
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.
157 -------------------
159 Back to `Table of Contents`_
161 .. _`Table of Contents`: index.html
162 .. _`customisation documentation`: customizing.html