Premiere version : mise en route du suivi.
[auf_roundup.git] / doc / .svn / text-base / admin_guide.txt.svn-base
1 ====================
2 Administration Guide
3 ====================
4
5 .. contents::
6
7 What does Roundup install?
8 ==========================
9
10 There's two "installations" that we talk about when using Roundup:
11
12 1. The installation of the software and its support files. This uses the
13    standard Python mechanism called "distutils" and thus Roundup's core code,
14    executable scripts and support data files are installed in Python's
15    directories. On Windows, this is typically:
16
17    Scripts
18      ``<python dir>\scripts\...``
19    Core code
20      ``<python dir>\lib\site-packages\roundup\...``
21    Support files
22      ``<python dir>\share\roundup\...``
23
24    and on Unix-like systems (eg. Linux):
25
26    Scripts
27      ``<python root>/bin/...``
28    Core code
29      ``<python root>/lib-<python version>/site-packages/roundup/...``
30    Support files
31      ``<python root>/share/roundup/...``
32
33 2. The installation of a specific tracker. When invoking the roundup-admin
34    "inst" (and "init") commands, you're creating a new Roundup tracker. This
35    installs configuration files, HTML templates, detector code and a new
36    database. You have complete control over where this stuff goes through
37    both choosing your "tracker home" and the ``main`` -> ``database`` variable
38    in the tracker's config.ini.
39
40
41 Configuring Roundup's Logging of Messages For Sysadmins
42 =======================================================
43
44 You may configure where Roundup logs messages in your tracker's config.ini
45 file. Roundup will use the standard Python (2.3+) logging implementation
46 when available. If not, then a very basic logging implementation will be used
47 (see BasicLogging in the roundup.rlog module for details).
48
49 Configuration for standard "logging" module:
50  - tracker configuration file specifies the location of a logging
51    configration file as ``logging`` -> ``config``
52  - ``roundup-server`` specifies the location of a logging configuration
53    file on the command line
54 Configuration for "BasicLogging" implementation:
55  - tracker configuration file specifies the location of a log file
56    ``logging`` -> ``filename``
57  - tracker configuration file specifies the level to log to as
58    ``logging`` -> ``level``
59  - ``roundup-server`` specifies the location of a log file on the command
60    line
61  - ``roundup-server`` specifies the level to log to on the command line
62
63 (``roundup-mailgw`` always logs to the tracker's log file)
64
65 In both cases, if no logfile is specified then logging will simply be sent
66 to sys.stderr with only logging of ERROR messages.
67
68
69 Configuring roundup-server
70 ==========================
71
72 The basic configuration file layout is as follows (take from the
73 ``roundup-server.ini.example`` file in the "doc" directory)::
74
75     [main]
76     port = 8080
77     ;hostname =
78     ;user =
79     ;group =
80     ;log_ip = yes
81     ;pidfile =
82     ;logfile =
83     ;template =
84     ;ssl = no
85     ;pem =
86
87     [trackers]
88     ; Add one of these per tracker being served
89     name = /path/to/tracker/name
90
91 Values ";commented out" are optional. The meaning of the various options
92 are as follows:
93
94 **port**
95   Defines the local TCP port to listen for clients on.
96 **hostname**
97   Defines the local hostname to listen for clients on. Only required if
98   "localhost" is not sufficient.
99 **user** and **group**
100   Defines the Unix user and group to run the server as. Only work if the
101   server is started as root.
102 **log_ip**
103   If ``yes`` then we log IP addresses against accesses. If ``no`` then we
104   log the hostname of the client. The latter can be much slower.
105 **pidfile**
106   If specified, the server will fork at startup and write its new PID to
107   the file.
108 **logfile**
109   Any unhandled exception messages or other output from Roundup will be
110   written to this file. It must be specified if **pidfile** is specified.
111   If per-tracker logging is specified, then very little will be written to
112   this file.
113 **template**
114   Specifies a template used for displaying the tracker index when
115   multiple trackers are being used. The variable "trackers" is available
116   to the template and is a dict of all configured trackers.
117 **ssl**
118   Enables the use of SSL to secure the connection to the roundup-server.
119   If you enable this, ensure that your tracker's config.ini specifies
120   an *https* URL.
121 **pem**
122   If specified, the SSL PEM file containing the private key and certificate.
123   If not specified, roundup will generate a temporary, self-signed certificate
124   for use.
125 **trackers** section
126   Each line denotes a mapping from a URL component to a tracker home.
127   Make sure the name part doesn't include any url-unsafe characters like
128   spaces. Stick to alphanumeric characters and you'll be ok.
129
130
131 Users and Security
132 ==================
133
134 Roundup holds its own user database which primarily contains a username,
135 password and email address for the user. Roundup *must* have its own user
136 listing, in order to maintain internal consistency of its data. It is a
137 relatively simple exercise to update this listing on a regular basis, or on
138 demand, so that it matches an external listing (eg. unix passwd file, LDAP,
139 etc.)
140
141 Roundup identifies users in a number of ways:
142
143 1. Through the web, users may be identified by either HTTP Basic
144    Authentication or cookie authentication. If you are running the web
145    server (roundup-server) through another HTTP server (eg. apache or IIS)
146    then that server may require HTTP Basic Authentication, and it will pass
147    the ``REMOTE_USER`` variable through to Roundup. If this variable is not
148    present, then Roundup defaults to using its own cookie-based login
149    mechanism.
150 2. In email messages handled by roundup-mailgw, users are identified by the
151    From address in the message.
152
153 In both cases, Roundup's behaviour when dealing with unknown users is
154 controlled by Permissions defined in the "SECURITY SETTINGS" section of the
155 tracker's ``schema.py`` module:
156
157 Web Registration
158   If granted to the Anonymous Role, then anonymous users will be able to
159   register through the web.
160 Email Registration
161   If granted to the Anonymous Role, then email messages from unknown users
162   will result in those users being registered with the tracker.
163
164 More information about how to customise your tracker's security settings
165 may be found in the `customisation documentation`_.
166
167
168 Tasks
169 =====
170
171 Maintenance of Roundup can involve one of the following:
172
173 1. `tracker backup`_
174 2. `software upgrade`_
175 3. `migrating backends`_
176 4. `moving a tracker`_
177 5. `migrating from other software`_
178 6. `adding a user from the command-line`_
179
180
181 Tracker Backup
182 --------------
183
184 The roundup-admin import and export commands are **not** recommended for
185 performing backup.
186
187 Optionally stop the web and email frontends and to copy the contents of the
188 tracker home directory to some other place using standard backup tools.
189 This means using
190 *pg_dump* to take a snapshot of your Postgres backend database, for example.
191 A simple copy of the tracker home (and files storage area if you've configured
192 it to be elsewhere) will then complete the backup.
193
194
195 Software Upgrade
196 ----------------
197
198 Always make a backup of your tracker before upgrading software. Steps you may
199 take:
200
201 1. Ensure that the unit tests run on your system::
202
203     python run_tests.py
204
205 2. If you're using an RDBMS backend, make a backup of its contents now.
206 3. Make a backup of the tracker home itself.
207 4. Stop the tracker web and email frontends.
208 5. Install the new version of the software::
209
210     python setup.py install
211
212 6. Follow the steps in the `upgrading documentation`_ for the new version of
213    the software in the copied.
214
215    Usually you will be asked to run `roundup_admin migrate` on your tracker
216    before you allow users to start accessing the tracker.
217
218    It's safe to run this even if it's not required, so just get into the
219    habit.
220 7. Restart your tracker web and email frontends.
221
222 If something bad happens, you may reinstate your backup of the tracker and
223 reinstall the older version of the sofware using the same install command::
224
225     python setup.py install
226
227
228 Migrating Backends
229 ------------------
230
231 1. Stop the existing tracker web and email frontends (preventing changes).
232 2. Use the roundup-admin tool "export" command to export the contents of
233    your tracker to disk.
234 3. Copy the tracker home to a new directory.
235 4. Delete the "db" directory from the new directory.
236 5. Enter the new backend name in the tracker home ``db/backend_name`` file.
237 6. Use the roundup-admin "import" command to import the previous export with
238    the new tracker home. If non-interactively::
239      
240      roundup-admin -i <tracker home> import <tracker export dir>
241
242    If interactively, enter 'commit' before exitting.
243 7. Test each of the admin tool, web interface and mail gateway using the new
244    backend.
245 8. Move the old tracker home out of the way (rename to "tracker.old") and
246    move the new tracker home into its place.
247 9. Restart web and email frontends.
248
249
250 Moving a Tracker
251 ----------------
252
253 If you're moving the tracker to a similar machine, you should:
254
255 1. install Roundup on the new machine and test that it works there,
256 2. stop the existing tracker web and email frontends (preventing changes),
257 3. copy the tracker home directory over to the new machine, and
258 4. start the tracker web and email frontends on the new machine.
259
260 Most of the backends are actually portable across platforms (ie. from Unix to
261 Windows to Mac). If this isn't the case (ie. the tracker doesn't work when
262 moved using the above steps) then you'll need to:
263
264 1. install Roundup on the new machine and test that it works there,
265 2. stop the existing tracker web and email frontends (preventing changes),
266 3. use the roundup-admin tool "export" command to export the contents of
267    the existing tracker,
268 4. copy the export to the new machine,
269 5. use the roundup-admin "import" command to import the tracker on the new
270    machine, and
271 6. start the tracker web and email frontends on the new machine.
272
273
274 Migrating From Other Software
275 -----------------------------
276
277 You have a couple of choices. You can either use a CSV import into Roundup,
278 or you can write a simple Python script which uses the Roundup API
279 directly. The latter is almost always simpler -- see the "scripts"
280 directory in the Roundup source for some example uses of the API.
281
282 "roundup-admin import" will import data into your tracker from a
283 directory containing files with the following format:
284
285 - one colon-separated-values file per Class with columns for each property,
286   named <classname>.csv
287 - one colon-separated-values file per Class with journal information,
288   named <classname>-journals.csv (this is required, even if it's empty)
289 - if the Class is a FileClass, you may have the "content" property
290   stored in separate files from the csv files. This goes in a directory
291   structure::
292
293       <classname>-files/<N>/<designator>
294
295   where ``<designator>`` is the item's ``<classname><id>`` combination.
296   The ``<N>`` value is ``int(<id> / 1000)``.
297
298
299 Adding A User From The Command-Line
300 -----------------------------------
301
302 The ``roundup-admin`` program can create any data you wish to in the
303 database. To create a new user, use::
304
305     roundup-admin create user
306
307 To figure out what good values might be for some of the fields (eg. Roles)
308 you can just display another user::
309
310     roundup-admin list user
311
312 (or if you know their username, and it happens to be "richard")::
313
314     roundup-admin find username=richard
315
316 then using the user id you get from one of the above commands, you may
317 display the user's details::
318
319     roundup-admin display <userid>
320
321
322 Running the Servers
323 ===================
324
325 Unix
326 ----
327
328 On Unix systems, use the scripts/server-ctl script to control the
329 roundup-server server. Copy it somewhere and edit the variables at the top
330 to reflect your specific installation.
331
332
333 Windows
334 -------
335
336 On Windows, the roundup-server program runs as a Windows Service, and
337 therefore may be controlled through the Services control panel. The
338 roundup-server program may also control the service directly:
339
340 **install the service**
341   ``roundup-server -C /path/to/my/roundup-server.ini -c install``
342 **start the service**
343   ``roundup-server -c start``
344 **stop the service**
345   ``roundup-server -c stop``
346
347 To bring up the services panel:
348
349 Windows 2000 and later
350   Start/Control Panel/Administrative Tools/Services
351 Windows NT4
352   Start/Control Panel/Services
353
354 You will need a server configuration file (as described in
355 `Configuring roundup-server`_) for specifying tracker homes
356 and other roundup-server configuration. Specify the name of
357 this file using the ``-C`` switch when installing the service.
358
359 Running the Mail Gateway Script
360 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
361
362 The mail gateway script should be scheduled to run regularly on your
363 Windows server. Normally this will result in a window popping up. The
364 solution to this is to:
365
366 1. Create a new local account on the Roundup server
367 2. Set the scheduled task to run in the context of this user instead
368    of your normal login
369
370
371 .. _`customisation documentation`: customizing.html
372 .. _`upgrading documentation`: upgrading.html