Premiere version : mise en route du suivi.
[auf_roundup.git] / doc / .svn / text-base / installation.txt.svn-base
1 ==================
2 Installing Roundup
3 ==================
4
5 .. contents::
6    :depth: 2
7
8
9 Overview
10 ========
11
12 Broken out separately, there are several conceptual pieces to a
13 Roundup installation:
14
15 Roundup trackers
16  Trackers consist of issues (be they bug reports or otherwise), tracker
17  configuration file(s), web HTML files etc. Roundup trackers are initialised
18  with a "Template" which defines the fields usable/assignable on a
19  per-issue basis.  Descriptions of the provided templates are given in
20  `choosing your template`_.
21
22 Roundup support code
23  Installed into your Python install's lib directory.
24
25 Roundup scripts
26  These include the email gateway, the roundup
27  HTTP server, the roundup administration command-line interface, etc.
28
29
30 Prerequisites
31 =============
32
33 Roundup requires Python 2.3 or newer (but not Python 3) with a functioning
34 anydbm module. Download the latest version from http://www.python.org/.
35 It is highly recommended that users install the latest patch version
36 of python as these contain many fixes to serious bugs.
37
38 Some variants of Linux will need an additional "python dev" package
39 installed for Roundup installation to work. Debian and derivatives, are
40 known to require this.
41
42 If you're on windows, you will either need to be using the ActiveState python
43 distribution (at http://www.activestate.com/Products/ActivePython/), or you'll
44 have to install the win32all package separately (get it from
45 http://starship.python.net/crew/mhammond/win32/).
46
47
48 Optional Components
49 ===================
50
51 You may optionally install and use:
52
53 Timezone Definitions
54   Full timezone support requires pytz_ module (version 2005i or later)
55   which brings the `Olson tz database`_ into Python.  If pytz_ is not
56   installed, timezones may be specified as numeric hour offsets only.
57
58 An RDBMS
59   Sqlite, MySQL and Postgresql are all supported by Roundup and will be
60   used if available. One of these is recommended if you are anticipating a
61   large user base (see `choosing your backend`_ below).
62
63 Xapian full-text indexer
64   The Xapian_ full-text indexer is also supported and will be used by
65   default if it is available. This is strongly recommended if you are
66   anticipating a large number of issues (> 5000).
67
68   You may install Xapian at any time, even after a tracker has been
69   installed and used. You will need to run the "roundup-admin reindex"
70   command if the tracker has existing data.
71
72   Roundup requires Xapian *newer* than 0.9.2 - it may be necessary for
73   you to install a snapshot. Snapshot "0.9.2_svn6532" has been tried
74   successfully.
75
76 pyopenssl
77   If pyopenssl_ is installed the roundup-server can be configured
78   to serve trackers over SSL. If you are going to serve roundup via
79   proxy through a server with SSL support (e.g. apache) then this is
80   unnecessary.
81
82 pyme
83   If pyme_ is installed you can configure the mail gateway to perform
84   verification or decryption of incoming OpenPGP MIME messages. When
85   configured, you can require email to be cryptographically signed
86   before roundup will allow it to make modifications to issues.
87
88 .. _Xapian: http://www.xapian.org/
89 .. _pytz: http://www.python.org/pypi/pytz
90 .. _Olson tz database: http://www.twinsun.com/tz/tz-link.htm
91 .. _pyopenssl: http://pyopenssl.sourceforge.net
92 .. _pyme: http://pyme.sourceforge.net
93
94
95 Getting Roundup
96 ===============
97
98 .. note::
99     Some systems, such as Debian and NetBSD, already have Roundup
100     installed. Try running the command "roundup-admin" with no arguments,
101     and if it runs you may skip the `Basic Installation Steps`_
102     below and go straight to `configuring your first tracker`_.
103
104 Download the latest version from http://roundup.sf.net/.
105
106 If you're using WinZIP's "classic" interface, make sure the "Use
107 folder names" check box is checked before you extract the files.
108
109
110 For The Really Impatient
111 ========================
112
113 If you just want to give Roundup a whirl Right Now, then simply run
114 ``roundup-demo``.
115
116 This will set up a simple demo tracker on your machine. [1]_
117 When it's done, it'll print out a URL to point your web browser at
118 so you may start playing. Three users will be set up:
119
120 1. anonymous - the "default" user with permission to do very little
121 2. demo (password "demo") - a normal user who may create issues
122 3. admin (password "admin") - an administrative user who has complete
123    access to the tracker
124
125 .. [1] Demo tracker is set up to be accessed by localhost browser.
126        If you run demo on a server host, please stop the demo when
127        it has shown startup notice, open file ``demo/config.ini`` with
128        your editor, change host name in the ``web`` option in section
129        ``[tracker]``, save the file, then re-run the demo program.
130
131 Installation
132 ============
133
134 Set aside 15-30 minutes. There's several steps to follow in your
135 installation:
136
137 1. `basic installation steps`_ if Roundup is not installed on your system
138 2. `configuring your first tracker`_ that all installers must follow
139 3. then optionally `configure a web interface`_
140 4. and optionally `configure an email interface`_
141 5. `UNIX environment steps`_ to take if you're installing on a shared
142    UNIX machine and want to restrict local access to roundup
143 6. `additional language codecs`_
144
145 For information about how Roundup installs, see the `administration
146 guide`_.
147
148
149 Basic Installation Steps
150 ------------------------
151
152 To install the Roundup support code into your Python tree and
153 Roundup scripts into /usr/bin (substitute that path for whatever is
154 appropriate on your system). You need to have write permissions
155 for these locations, eg. being root on unix::
156
157     python setup.py install
158
159 If you would like to place the Roundup scripts in a directory other
160 than ``/usr/bin``, then specify the preferred location with
161 ``--install-scripts``. For example, to install them in
162 ``/opt/roundup/bin``::
163
164     python setup.py install --install-scripts=/opt/roundup/bin
165
166 You can also use the ``--prefix`` option to use a completely different
167 base directory, if you do not want to use administrator rights. If you
168 choose to do this, you may have to change Python's search path (sys.path)
169 yourself.
170
171
172 Configuring your first tracker
173 ------------------------------
174
175 1. To create a Roundup tracker (necessary to do before you can
176    use the software in any real fashion), you need to set up a "tracker
177    home":
178
179    a. (Optional) If you intend to keep your roundup trackers
180       under one top level directory which does not exist yet,
181       you should create that directory now.  Example::
182
183          mkdir /opt/roundup/trackers
184
185    b. Either add the Roundup script location to your ``PATH``
186       environment variable or specify the full path to
187       the command in the next step.
188
189    c. Install a new tracker with the command ``roundup-admin install``.
190       You will be asked a series of questions.  Descriptions of the provided
191       templates can be found in `choosing your template`_ below.  Descriptions
192       of the available backends can be found in `choosing your backend`_
193       below.  The questions will be something like (you may have more
194       templates or backends available)::
195
196           Enter tracker home: /opt/roundup/trackers/support
197           Templates: classic
198           Select template [classic]: classic
199           Back ends: anydbm, mysql, sqlite
200           Select backend [anydbm]: anydbm
201
202       Note: "Back ends" selection list depends on availability of
203       third-party database modules.  Standard python distribution
204       includes anydbm module only.
205
206       The "support" part of the tracker name can be anything you want - it
207       is going to be used as the directory that the tracker information
208       will be stored in.
209
210       You will now be directed to edit the tracker configuration and
211       initial schema.  At a minimum, you must set "main :: admin_email"
212       (that's the "admin_email" option in the "main" section) "mail ::
213       host", "tracker :: web" and "mail :: domain".  If you get stuck,
214       and get configuration file errors, then see the `tracker
215       configuration`_ section of the `customisation documentation`_.
216
217       If you just want to get set up to test things quickly (and follow
218       the instructions in step 3 below), you can even just set the
219       "tracker :: web" variable to::
220
221          web = http://localhost:8080/support/
222
223       The URL *must* end in a '/', or your web interface *will not work*.
224       See `Customising Roundup`_ for details on configuration and schema
225       changes. You may change any of the configuration after
226       you've initialised the tracker - it's just better to have valid values
227       for this stuff now.
228
229    d. Initialise the tracker database with ``roundup-admin initialise``.
230       You will need to supply an admin password at this step. You will be
231       prompted::
232
233           Admin Password:
234                  Confirm:
235
236       Note: running this command will *destroy any existing data in the
237       database*. In the case of MySQL and PostgreSQL, any existing database
238       will be dropped and re-created.
239
240       Once this is done, the tracker has been created.
241
242 2. At this point, your tracker is set up, but doesn't have a nice user
243    interface. To set that up, we need to `configure a web interface`_ and
244    optionally `configure an email interface`_. If you want to try your
245    new tracker out, assuming "tracker :: web" is set to
246    ``'http://localhost:8080/support/'``, run::
247
248      roundup-server support=/opt/roundup/trackers/support
249
250    then direct your web browser at:
251
252      http://localhost:8080/support/
253
254    and you should see the tracker interface.
255
256
257 Choosing Your Template
258 ----------------------
259
260 Classic Template
261 ~~~~~~~~~~~~~~~~
262
263 The classic template is the one defined in the `Roundup Specification`_. It
264 holds issues which have priorities and statuses. Each issue may also have a
265 set of messages which are disseminated to the issue's list of nosy users.
266
267 Minimal Template
268 ~~~~~~~~~~~~~~~~
269
270 The minimal template has the minimum setup required for a tracker
271 installation. That is, it has the configuration files, defines a user database
272 and the basic HTML interface to that. It's a completely clean slate for you to
273 create your tracker on.
274
275
276 Choosing Your Backend
277 ---------------------
278
279 The actual storage of Roundup tracker information is handled by backends.
280 There's several to choose from, each with benefits and limitations:
281
282 ========== =========== ===== ==============================
283 Name       Speed       Users   Support
284 ========== =========== ===== ==============================
285 anydbm     Slowest     Few   Always available
286 sqlite     Fastest(*)  Few   May need install (PySQLite_)
287 postgresql Fast        Many  Needs install/admin (psycopg_)
288 mysql      Fast        Many  Needs install/admin (MySQLdb_)
289 ========== =========== ===== ==============================
290
291 **sqlite**
292   This uses the embedded database engine PySQLite_ to provide a very fast
293   backend. This is not suitable for trackers which will have many
294   simultaneous users, but requires much less installation and maintenance
295   effort than more scalable postgresql and mysql backends.
296
297   SQLite is supported via PySQLite versions 1.1.7, 2.1.0 and sqlite3 (the last
298   being bundled with Python 2.5+)
299
300   Installed SQLite should be the latest version available (3.3.8 is known
301   to work, 3.1.3 is known to have problems).
302 **postgresql**
303   Backend for popular RDBMS PostgreSQL. You must read doc/postgresql.txt for
304   additional installation steps and requirements. You must also configure
305   the ``rdbms`` section of your tracker's ``config.ini``.  It is recommended
306   that you use at least version 1.1.21 of psycopg.
307 **mysql**
308   Backend for popular RDBMS MySQL. You must read doc/mysql.txt for additional
309   installation steps and requirements. You must also configure the ``rdbms``
310   section of your tracker's ``config.ini``
311
312 You may defer your decision by setting your tracker up with the anydbm
313 backend (which is guaranteed to be available) and switching to one of the
314 other backends at any time using the instructions in the `administration
315 guide`_.
316
317 Regardless of which backend you choose, Roundup will attempt to initialise
318 a new database for you when you run the roundup-admin "initialise" command.
319 In the case of MySQL and PostgreSQL you will need to have the appropriate
320 privileges to create databases.
321
322
323 Configure a Web Interface
324 -------------------------
325
326 There are five web interfaces to choose from:
327
328 1. `web server cgi-bin`_
329 2. `cgi-bin for limited-access hosting`_
330 3. `stand-alone web server`_
331 4. `Zope product - ZRoundup`_
332 5. `Apache HTTP Server with mod_python`_
333 6. `WSGI handler`_
334
335 You may need to give the web server user permission to access the tracker home
336 - see the `UNIX environment steps`_ for information. You may also need to
337 configure your system in some way - see `platform-specific notes`_.
338
339
340 Web Server cgi-bin
341 ~~~~~~~~~~~~~~~~~~
342
343 A benefit of using the cgi-bin approach is that it's the easiest way to
344 restrict access to your tracker to only use HTTPS. Access will be slower
345 than through the `stand-alone web server`_ though.
346
347 If your Python isn't installed as "python" then you'll need to edit
348 the ``roundup.cgi`` script to fix the first line.
349
350 If you're using IIS on a Windows platform, you'll need to run this command
351 for the cgi to work (it turns on the PATH_INFO cgi variable)::
352
353     adsutil.vbs set w3svc/AllowPathInfoForScriptMappings TRUE
354
355 The ``adsutil.vbs`` file can be found in either ``c:\inetpub\adminscripts``
356 or ``c:\winnt\system32\inetsrv\adminsamples\`` or
357 ``c:\winnt\system32\inetsrv\adminscripts\`` depending on your installation.
358
359 More information about ISS setup may be found at:
360
361    http://support.microsoft.com/default.aspx?scid=kb%3Ben-us%3B276494
362
363 Copy the ``frontends/roundup.cgi`` file to your web server's ``cgi-bin``
364 directory. You will need to configure it to tell it where your tracker home
365 is. You can do this either:
366
367 Through an environment variable
368   Set the variable TRACKER_HOMES to be a colon (":") separated list of
369   name=home pairs (if you're using apache, the SetEnv directive can do this)
370
371 Directly in the ``roundup.cgi`` file itself
372   Add your instance to the TRACKER_HOMES variable as ``'name': 'home'``
373
374 The "name" part of the configuration will appear in the URL and identifies the
375 tracker (so you may have more than one tracker per cgi-bin script). Make sure
376 there are no spaces or other illegal characters in it (to be safe, stick to
377 letters and numbers). The "name" forms part of the URL that appears in the
378 tracker config "tracker :: web" variable, so make sure they match. The "home"
379 part of the configuration is the tracker home directory.
380
381 If you're using Apache, you can use an additional trick to hide the
382 ``.cgi`` extension of the cgi script. Place the ``roundup.cgi`` script
383 wherever you want it to be, rename it to just ``roundup``, and add a
384 couple lines to your Apache configuration::
385
386  <Location /path/to/roundup>
387    SetHandler cgi-script
388  </Location>
389
390
391 CGI-bin for Limited-Access Hosting
392 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
393
394 If you are running in a shared-hosting environment or otherwise don't have
395 permissiong to edit the system web server's configuration, but can create a
396 ``.htaccess`` file then you may be able to use this approach.
397
398 1. Install flup_
399 2. Create a script ``roundup_stub`` in your server's ``cgi-bin`` directory
400    containing::
401
402     #!/usr/bin/env python
403
404     # if necessary modify the Python path to include the place you
405     # installed Roundup
406     #import sys
407     #sys.path.append('...')
408
409     # cgitb is needed for debugging in browser only
410     #import cgitb
411     #cgitb.enable()
412
413     # obtain the WSGI request dispatcher
414     from roundup.cgi.wsgi_handler import RequestDispatcher
415     tracker_home = '/path/to/tracker/home'
416     app = RequestDispatcher(tracker_home)
417
418     from flup.server.cgi import WSGIServer
419     WSGIServer(app).run()
420
421 3. Modify or created the ``.htaccess`` file in the desired (sub-)domain
422    directory to contain::
423
424     RewriteEngine On
425     RewriteBase /
426     RewriteRule ^(.*)$      /cgi-bin/roundup_stub/$1 [L]
427
428 Now loading the (sub-)domain in a browser should load the tracker web
429 interface. If you get a "500" error then enable the "cgitb" lines in the
430 stub to get some debugging information.
431
432
433 Stand-alone Web Server
434 ~~~~~~~~~~~~~~~~~~~~~~
435
436 This approach will give you faster response than cgi-bin. You may
437 investigate using ProxyPass or similar configuration in apache to have your
438 tracker accessed through the same URL as other systems.
439
440 The stand-alone web server is started with the command ``roundup-server``. It
441 has several options - display them with ``roundup-server -h``.
442
443 The tracker home configuration is similar to the cgi-bin - you may either edit
444 the script to change the TRACKER_HOMES variable or you may supply the
445 name=home values on the command-line after all the other options.
446
447 To make the server run in the background, use the "-d" option, specifying the
448 name of a file to write the server process id (pid) to.
449
450
451 Zope Product - ZRoundup
452 ~~~~~~~~~~~~~~~~~~~~~~~
453
454 ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
455 your Products directory either in INSTANCE_HOME/Products or the Zope
456 code tree lib/python/Products.
457
458 When you next (re)start up Zope, you will be able to add a ZRoundup object
459 that interfaces to your new tracker.
460
461 Apache HTTP Server with mod_python
462 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
463
464 `Mod_python`_ is an `Apache`_ module that embeds the Python interpreter
465 within the server.  Running Roundup this way is much faster than all
466 above options and, like `web server cgi-bin`_, allows you to use HTTPS
467 protocol.  The drawback is that this setup is more complicated.
468
469 The following instructions were tested on apache 2.0 with mod_python 3.1.
470 If you are using older versions, your mileage may vary.
471
472 Mod_python uses OS threads.  If your apache was built without threads
473 (quite commonly), you must load the threading library to run mod_python.
474 This is done by setting ``LD_PRELOAD`` to your threading library path
475 in apache ``envvars`` file.  Example for gentoo linux (``envvars`` file
476 is located in ``/usr/lib/apache2/build/``)::
477
478   LD_PRELOAD=/lib/libpthread.so.0
479   export LD_PRELOAD
480
481 Example for FreeBSD (``envvars`` is in ``/usr/local/sbin/``)::
482
483   LD_PRELOAD=/usr/lib/libc_r.so
484   export LD_PRELOAD
485
486 Next, you have to add Roundup trackers configuration to apache config.
487 Roundup apache interface uses the following options specified with
488 ``PythonOption`` directives:
489
490   TrackerHome:
491     defines the tracker home directory - the directory that was specified
492     when you did ``roundup-admin init``.  This option is required.
493
494   TrackerLanguage:
495     defines web user interface language.  mod_python applications do not
496     receive OS environment variables in the same way as command-line
497     programs, so the language cannot be selected by setting commonly
498     used variables like ``LANG`` or ``LC_ALL``.  ``TrackerLanguage``
499     value has the same syntax as values of these environment variables.
500     This option may be omitted.
501
502   TrackerDebug:
503     run the tracker in debug mode.  Setting this option to ``yes`` or
504     ``true`` has the same effect as running ``roundup-server -t debug``:
505     the database schema and used html templates are rebuilt for each
506     HTTP request.  Values ``no`` or ``false`` mean that all html
507     templates for the tracker are compiled and the database schema is
508     checked once at startup.  This is the default behaviour.
509
510   TrackerTiming:
511     has nearly the same effect as environment variable ``CGI_SHOW_TIMING``
512     for standalone roundup server.  The difference is that setting this
513     option to ``no`` or ``false`` disables timings display.  Value
514     ``comment`` writes request handling times in html comment, and
515     any other non-empty value makes timing report visible.  By default,
516     timing display is disabled.
517
518 In the following example we have two trackers set up in
519 ``/var/db/roundup/support`` and ``/var/db/roundup/devel`` and accessed
520 as ``https://my.host/roundup/support/`` and ``https://my.host/roundup/devel/``
521 respectively (provided Apache has been set up for SSL of course).
522 Having them share same parent directory allows us to
523 reduce the number of configuration directives.  Support tracker has
524 russian user interface.  The other tracker (devel) has english user
525 interface (default).
526
527 Static files from ``html`` directory are served by apache itself - this
528 is quicker and generally more robust than doing that from python.
529 Everything else is aliased to dummy (non-existing) ``py`` file,
530 which is handled by mod_python and our roundup module.
531
532 Example mod_python configuration::
533
534     #################################################
535     # Roundup Issue tracker
536     #################################################
537     # enable Python optimizations (like 'python -O')
538     PythonOptimize On
539     # let apache handle static files from 'html' directories
540     AliasMatch /roundup/(.+)/@@file/(.*) /var/db/roundup/$1/html/$2
541     # everything else is handled by roundup web UI
542     AliasMatch /roundup/([^/]+)/(?!@@file/)(.*) /var/db/roundup/$1/dummy.py/$2
543     # roundup requires a slash after tracker name - add it if missing
544     RedirectMatch permanent ^/roundup/([^/]+)$ /roundup/$1/
545     # common settings for all roundup trackers
546     <Directory /var/db/roundup/*>
547       Order allow,deny
548       Allow from all
549       AllowOverride None
550       Options None
551       AddHandler python-program .py
552       PythonHandler roundup.cgi.apache
553       # uncomment the following line to see tracebacks in the browser
554       # (note that *some* tracebacks will be displayed anyway)
555       #PythonDebug On
556     </Directory>
557     # roundup tracker homes
558     <Directory /var/db/roundup/support>
559       PythonOption TrackerHome /var/db/roundup/support
560       PythonOption TrackerLanguage ru
561     </Directory>
562     <Directory /var/db/roundup/devel>
563       PythonOption TrackerHome /var/db/roundup/devel
564     </Directory>
565
566 Notice that the ``/var/db/roundup`` path shown above refers to the directory
567 in which the tracker homes are stored. The actual value will thus depend on
568 your system.
569
570 On Windows the corresponding lines will look similar to these::
571
572     AliasMatch /roundup/(.+)/@@file/(.*) C:/DATA/roundup/$1/html/$2
573     AliasMatch /roundup/([^/]+)/(?!@@file/)(.*) C:/DATA/roundup/$1/dummy.py/$2
574     <Directory C:/DATA/roundup/*>
575     <Directory C:/DATA/roundup/support>
576     <Directory C:/DATA/roundup/devel>
577
578 In this example the directory hosting all of the tracker homes is
579 ``C:\DATA\roundup``. (Notice that you must use forward slashes in paths
580 inside the httpd.conf file!)
581
582 The URL for accessing these trackers then become:
583 `http://<roundupserver>/roundup/support/`` and
584 ``http://<roundupserver>/roundup/devel/``
585
586 Note that in order to use https connections you must set up Apache for secure
587 serving with SSL.
588
589 WSGI Handler
590 ~~~~~~~~~~~~
591
592 The WSGI handler is quite simple. The following sample code shows how
593 to use it::
594
595     from wsgiref.simple_server import make_server
596
597     # obtain the WSGI request dispatcher
598     from roundup.cgi.wsgi_handler import RequestDispatcher
599     tracker_home = 'demo'
600     app = RequestDispatcher(tracker_home)
601
602     httpd = make_server('', 8917, app)
603     httpd.serve_forever()
604
605 To test the above you should create a demo tracker with ``python demo.py``.
606 Edit the ``config.ini`` to change the web URL to "http://localhost:8917/".
607
608
609 Configure an Email Interface
610 ----------------------------
611
612 If you don't want to use the email component of Roundup, then remove the
613 "``nosyreaction.py``" module from your tracker "``detectors``" directory.
614
615 See `platform-specific notes`_ for steps that may be needed on your system.
616
617 There are five supported ways to get emailed issues into the
618 Roundup tracker.  You should pick ONE of the following, all
619 of which will continue my example setup from above:
620
621 As a mail alias pipe process
622 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
623
624 Set up a mail alias called "issue_tracker" as (include the quote marks):
625 "``|/usr/bin/python /usr/bin/roundup-mailgw <tracker_home>``"
626 (substitute ``/usr/bin`` for wherever roundup-mailgw is installed).
627
628 In some installations (e.g. RedHat Linux and Fedora Core) you'll need to
629 set up smrsh so sendmail will accept the pipe command. In that case,
630 symlink ``/etc/smrsh/roundup-mailgw`` to "``/usr/bin/roundup-mailgw``"
631 and change the command to::
632
633     |roundup-mailgw /opt/roundup/trackers/support
634
635 To test the mail gateway on unix systems, try::
636
637     echo test |mail -s '[issue] test' support@YOUR_DOMAIN_HERE
638
639 Be careful that some mail systems (postfix for example) will impost a
640 limits on processes they spawn. In particular postfix can set a file size
641 limit. *This can cause your Roundup database to become corrupted.*
642
643
644 As a custom router/transport using a pipe process (Exim4 specific)
645 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
646
647 The following configuration snippets for `Exim 4`_ configuration
648 implement a custom router & transport to accomplish mail delivery to
649 roundup-mailgw. A configuration for Exim3 is similar but not
650 included, since Exim3 is considered obsolete.
651
652 .. _Exim 4: http://www.exim.org/
653
654 This configuration is similar to the previous section, in that it uses
655 a pipe process. However, there are advantages to using a custom
656 router/transport process, if you are using Exim.
657
658 * This avoids privilege escalation, since otherwise the pipe process
659   will run as the mail user, typically mail. The transport can be
660   configured to run as the user appropriate for the task at hand. In the
661   transport described in this section, Exim4 runs as the unprivileged
662   user ``roundup``.
663
664 * Separate configuration is not required for each tracker
665   instance. When a email arrives at the server, Exim passes it through
666   the defined routers. The roundup_router looks for a match with one of
667   the roundup directories, and if there is one it is passed to the
668   roundup_transport, which uses the pipe process described in the
669   previous section (`As a mail alias pipe process`_).
670
671 The matching is done in the line::
672
673   require_files = /usr/bin/roundup-mailgw:ROUNDUP_HOME/$local_part/schema.py
674
675 The following configuration has been tested on Debian Sarge with
676 Exim4.
677
678 .. note::
679   Note that the Debian Exim4 packages don't allow pipes in alias files
680   by default, so the method described in the section `As a mail alias
681   pipe process`_ will not work with the default configuration. However,
682   the method described in this section does. See the discussion in
683   ``/usr/share/doc/exim4-config/README.system_aliases`` on any Debian
684   system with Exim4 installed.
685
686   For more Debian-specific information, see suggested addition to
687   README.Debian in
688   http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=343283, which will
689   hopefully be merged into the Debian package eventually.
690
691 This config makes a few assumptions:
692
693 * That the mail address corresponding to the tracker instance has the
694   same name as the directory of the tracker instance, i.e. the mail
695   interface address corresponding to a Roundup instance called
696   ``/var/lib/roundup/trackers/mytracker`` is ``mytracker@your.host``.
697
698 * That (at least) all the db subdirectories of all the tracker
699   instances (ie. ``/var/lib/roundup/trackers/*/db``) are owned by the same
700   user, in this case, 'roundup'.
701
702 * That if the ``schema.py`` file exists, then the tracker is ready for
703   use. Another option is to use the ``config.ini`` file (this changed
704   in 0.8 from ``config.py``).
705
706 Macros for Roundup router/transport. Should be placed in the macros
707 section of the Exim4 config::
708
709   # Home dir for your Roundup installation
710   ROUNDUP_HOME=/var/lib/roundup/trackers
711
712   # User and group for Roundup.
713   ROUNDUP_USER=roundup
714   ROUNDUP_GROUP=roundup
715
716 Custom router for Roundup. This will (probably) work if placed at the
717 beginning of the router section of the Exim4 config::
718
719   roundup_router:
720       driver = accept
721       # The config file config.ini seems like a more natural choice, but the
722       # file config.py was replaced by config.ini in 0.8, and schema.py needs
723       # to be present too.
724       require_files = /usr/bin/roundup-mailgw:ROUNDUP_HOME/$local_part/schema.py
725       transport = roundup_transport
726
727 Custom transport for Roundup. This will (probably) work if placed at
728 the beginning of the router section of the Exim4 config::
729
730   roundup_transport:
731       driver = pipe
732       command = /usr/bin/python /usr/bin/roundup-mailgw ROUNDUP_HOME/$local_part/
733       current_directory = ROUNDUP_HOME
734       home_directory = ROUNDUP_HOME
735       user = ROUNDUP_USER
736       group = ROUNDUP_GROUP
737
738 As a regular job using a mailbox source
739 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
740
741 Set ``roundup-mailgw`` up to run every 10 minutes or so. For example
742 (substitute ``/usr/bin`` for wherever roundup-mailgw is installed)::
743
744   0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support mailbox <mail_spool_file>
745
746 Where the ``mail_spool_file`` argument is the location of the roundup submission
747 user's mail spool. On most systems, the spool for a user "issue_tracker"
748 will be "``/var/mail/issue_tracker``".
749
750 As a regular job using a POP source
751 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
752
753 To retrieve from a POP mailbox, use a *cron* entry similar to the mailbox
754 one (substitute ``/usr/bin`` for wherever roundup-mailgw is
755 installed)::
756
757   0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support pop <pop_spec>
758
759 where pop_spec is "``username:password@server``" that specifies the roundup
760 submission user's POP account name, password and server.
761
762 On windows, you would set up the command using the windows scheduler.
763
764 As a regular job using an IMAP source
765 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
766
767 To retrieve from an IMAP mailbox, use a *cron* entry similar to the
768 POP one (substitute ``/usr/bin`` for wherever roundup-mailgw is
769 installed)::
770
771   0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support imap <imap_spec>
772
773 where imap_spec is "``username:password@server``" that specifies the roundup
774 submission user's IMAP account name, password and server. You may
775 optionally include a mailbox to use other than the default ``INBOX`` with
776 "``imap username:password@server mailbox``".
777
778 If you have a secure (ie. HTTPS) IMAP server then you may use ``imaps``
779 in place of ``imap`` in the command to use a secure connection.
780
781 As with the POP job, on windows, you would set up the command using the
782 windows scheduler.
783
784
785 UNIX Environment Steps
786 ----------------------
787
788 Each tracker ideally should have its own UNIX group, so create
789 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
790 you're using NIS).  To continue with my examples so far, I would
791 create the UNIX group 'support', although the name of the UNIX
792 group does not have to be the same as the tracker name.  To this
793 'support' group I then add all of the UNIX usernames who will be
794 working with this Roundup tracker.  In addition to 'real' users,
795 the Roundup email gateway will need to have permissions to this
796 area as well, so add the user your mail service runs as to the
797 group (typically "mail" or "daemon").  The UNIX group might then
798 look like::
799
800      support:*:1002:jblaine,samh,geezer,mail
801
802 If you intend to use the web interface (as most people do), you
803 should also add the username your web server runs as to the group.
804 My group now looks like this::
805
806      support:*:1002:jblaine,samh,geezer,mail,apache
807
808 The tracker "db" directory should be chmod'ed g+sw so that the group can
809 write to the database, and any new files created in the database will be owned
810 by the group.
811
812 If you're using the mysql or postgresql backend then you'll need to ensure
813 that the tracker user has appropriate permissions to create/modify the
814 database. If you're using roundup.cgi, the apache user needs permissions
815 to modify the database.  Alternatively, explicitly specify a database login
816 in ``rdbms`` -> ``user`` and ``password`` in ``config.ini``.
817
818 An alternative to the above is to create a new user who has the sole
819 responsibility of running roundup. This user:
820
821 1. runs the CGI interface daemon
822 2. runs regular polls for email
823 3. runs regular checks (using cron) to ensure the daemon is up
824 4. optionally has no login password so that nobody but the "root" user
825    may actually login and play with the roundup setup.
826
827 If you're using a Linux system (e.g. Fedora Core) with SELinux enabled,
828 you will need to ensure that the db directory has a context that
829 permits the web server to modify and create files. If you're using the
830 mysql or postgresql backend you may also need to update your policy to
831 allow the web server to access the database socket.
832
833
834 Additional Language Codecs
835 --------------------------
836
837 If you intend to send messages to Roundup that use Chinese, Japanese or
838 Korean encodings the you'll need to obtain CJKCodecs from
839 http://cjkpython.berlios.de/
840
841
842 Public Tracker Considerations
843 -----------------------------
844
845 If you run a public tracker, you will eventually have to think about
846 dealing with spam entered through both the web and mail interfaces.
847
848 The `customisation documentation`_ has a simple detector that will block
849 a lot of spam attempts. Look for the example "Preventing SPAM".
850
851
852 Maintenance
853 ===========
854
855 Read the separate `administration guide`_ for information about how to
856 perform common maintenance tasks with Roundup.
857
858
859 Upgrading
860 =========
861
862 Read the separate `upgrading document`_, which describes the steps needed to
863 upgrade existing tracker trackers for each version of Roundup that is
864 released.
865
866
867 Further Reading
868 ===============
869
870 If you intend to use Roundup with anything other than the default
871 templates, if you would like to hack on Roundup, or if you would
872 like implementation details, you should read `Customising Roundup`_.
873
874
875 Running Multiple Trackers
876 =========================
877
878 Things to think about before you jump off the deep end and install
879 multiple trackers, which involve additional URLs, user databases, email
880 addresses, databases to back up, etc.
881
882 1. Do you want a tracker per product you sell/support? You can just add
883    a new property to your issues called Product, and filter by that. See
884    the customisation example `adding a new field to the classic schema`_.
885 2. Do you want to track internal software development issues and customer
886    support issues separately? You can just set up an additional "issue"
887    class called "cust_issues" in the same tracker, mimicing the normal
888    "issue" class, but with different properties. See the customisation
889    example `tracking different types of issues`_.
890
891
892 Platform-Specific Notes
893 =======================
894
895 Windows command-line tools
896 --------------------------
897
898 To make the command-line tools accessible in Windows, you need to update
899 the "Path" environment variable in the Registry via a dialog box.
900
901 On Windows 2000 and later:
902
903 1) Press the "Start" button.
904 2) Choose "Settings"
905 3) Choose "Control Panel"
906 4) Choose "System"
907 5) Choose "Advanced"
908 6) Choose "Environmental Variables"
909 7) Add: "<dir>\Scripts" to the "Path" environmental variable.
910
911 Where <dir> in 7) is the root directory (e.g., ``C:\Python22\Scripts``)
912 of your Python installation.
913
914 I understand that in XP, 2) above is not needed as "Control
915 Panel" is directly accessible from "Start".
916
917 I do not believe this is possible to do in previous versions of Windows.
918
919
920 Windows Server
921 --------------
922
923 To have the Roundup web server start up when your machine boots up, there
924 are two different methods, the scheduler and installing the service.
925
926
927 1. Using the Windows scheduler
928 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
929
930 Set up the following in Scheduled Tasks (note, the following is for a
931 cygwin setup):
932
933 **Run**
934
935     ``c:\cygwin\bin\bash.exe -c "roundup-server TheProject=/opt/roundup/trackers/support"``
936
937 **Start In**
938
939     ``C:\cygwin\opt\roundup\bin``
940
941 **Schedule**
942
943     At System Startup
944
945 To have the Roundup mail gateway run periodically to poll a POP email address,
946 set up the following in Scheduled Tasks:
947
948 **Run**
949
950     ``c:\cygwin\bin\bash.exe -c "roundup-mailgw /opt/roundup/trackers/support pop roundup:roundup@mail-server"``
951
952 **Start In**
953
954     ``C:\cygwin\opt\roundup\bin``
955
956 **Schedule**
957
958     Every 10 minutes from 5:00AM for 24 hours every day
959
960     Stop the task if it runs for 8 minutes
961
962
963 2. Installing the roundup server as a Windows service
964 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
965
966 This is more Windows oriented and will make the Roundup server run as
967 soon as the PC starts up without any need for a login or such. It will
968 also be available in the normal Windows Administrative Tools.
969
970 For this you need first to create a service ini file containing the
971 relevant settings.
972
973 1. It is created if you execute the following command from within the
974    scripts directory (notice the use of backslashes)::
975
976      roundup-server -S -C <trackersdir>\server.ini -n <servername> -p 8080 -l <trackersdir>\trackerlog.log software=<trackersdir>\Software
977
978    where the item ``<trackersdir>`` is replaced with the physical directory
979    that hosts all of your trackers. The ``<servername>`` item is the name
980    of your roundup server PC, such as w2003srv or similar.
981
982 2. Next open the now created file ``C:\DATA\roundup\server.ini`` file
983    (if your ``<trackersdir>`` is ``C:\DATA\roundup``).
984    Check the entries for correctness, especially this one::
985
986     [trackers]
987     software = C:\DATA\Roundup\Software
988
989    (this is an example where the tracker is named software and its home is
990    ``C:\DATA\Roundup\Software``)
991
992 3. Next give the commands that actually installs and starts the service::
993
994     roundup-server -C C:\DATA\Roundup\server.ini -c install
995     roundup-server -c start
996
997 4. Finally open the AdministrativeTools/Services applet and locate the
998    Roundup service entry. Open its properties and change it to start
999    automatically instead of manually.
1000
1001 If you are using Apache as the webserver you might want to use it with
1002 mod_python instead to serve out Roundup. In that case see the mod_python
1003 instructions above for details.
1004
1005
1006 Sendmail smrsh
1007 --------------
1008
1009 If you use Sendmail's ``smrsh`` mechanism, you will need to tell
1010 smrsh that roundup-mailgw is a valid/trusted mail handler
1011 before it will work.
1012
1013 This is usually done via the following 2 steps:
1014
1015 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
1016    which points to the full path of your actual ``roundup-mailgw``
1017    script.
1018
1019 2. change your alias to ``"|roundup-mailgw <tracker_home>"``
1020
1021
1022 Linux
1023 -----
1024
1025 Make sure you read the instructions under `UNIX environment steps`_.
1026
1027
1028 Solaris
1029 -------
1030
1031 You'll need to build Python.
1032
1033 Make sure you read the instructions under `UNIX environment steps`_.
1034
1035
1036 Problems? Testing your Python...
1037 ================================
1038
1039 .. note::
1040    The ``run_tests.py`` script is packaged in Roundup's source distribution
1041    - users of the Windows installer, other binary distributions or
1042    pre-installed Roundup will need to download the source to use it.
1043
1044    Remember to have a database user 'rounduptest' prepared (with
1045    password 'rounduptest'). This user
1046    must have at least the rights to create and drop databases.
1047    Documentation: details on `adding MySQL users`_,
1048    for PostgreSQL you want to call the ``createuser`` command with the
1049    ``-d`` option to allow database creation.
1050
1051 Once you've unpacked roundup's source, run ``python run_tests.py`` in the
1052 source directory and make sure there are no errors. If there are errors,
1053 please let us know!
1054
1055 If the above fails, you may be using the wrong version of python. Try
1056 ``python2 run_tests.py`` or ``python2.X run_tests.py`` where ``X`` is in
1057 the set 3,4,5,6 depending on the version(s) of python installed.
1058 If that works, you will need to substitute ``python2`` or ``python2.X``
1059 for ``python`` in all further commands you use in relation to Roundup --
1060 from installation and scripts.
1061
1062
1063 .. _`table of contents`: index.html
1064 .. _`user guide`: user_guide.html
1065 .. _`roundup specification`: spec.html
1066 .. _`tracker configuration`: customizing.html#tracker-configuration
1067 .. _`customisation documentation`: customizing.html
1068 .. _`Adding a new field to the classic schema`:
1069    customizing.html#adding-a-new-field-to-the-classic-schema
1070 .. _`Tracking different types of issues`:
1071    customizing.html#tracking-different-types-of-issues
1072 .. _`customising roundup`: customizing.html
1073 .. _`upgrading document`: upgrading.html
1074 .. _`administration guide`: admin_guide.html
1075
1076
1077 .. _External hyperlink targets:
1078
1079 .. _apache: http://httpd.apache.org/
1080 .. _flup: http://pypi.python.org/pypi/flup
1081 .. _mod_python: http://www.modpython.org/
1082 .. _MySQLdb: http://sourceforge.net/projects/mysql-python
1083 .. _Psycopg: http://initd.org/software/initd/psycopg
1084 .. _pysqlite: http://pysqlite.org/
1085 .. _`adding MySQL users`:
1086     http://dev.mysql.com/doc/refman/5.1/en/adding-users.html