1 ==================
2 Installing Roundup
3 ==================
5 .. contents::
6 :depth: 2
9 Overview
10 ========
12 Broken out separately, there are several conceptual pieces to a
13 Roundup installation:
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`_.
22 Roundup support code
23 Installed into your Python install's lib directory.
25 Roundup scripts
26 These include the email gateway, the roundup
27 HTTP server, the roundup administration command-line interface, etc.
30 Prerequisites
31 =============
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.
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.
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/).
48 Optional Components
49 ===================
51 You may optionally install and use:
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.
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).
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).
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.
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.
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.
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.
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
95 Getting Roundup
96 ===============
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`_.
104 Download the latest version from http://roundup.sf.net/.
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.
110 For The Really Impatient
111 ========================
113 If you just want to give Roundup a whirl Right Now, then simply run
114 ``roundup-demo``.
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:
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
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.
131 Installation
132 ============
134 Set aside 15-30 minutes. There's several steps to follow in your
135 installation:
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`_
145 For information about how Roundup installs, see the `administration
146 guide`_.
149 Basic Installation Steps
150 ------------------------
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::
157 python setup.py install
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``::
164 python setup.py install --install-scripts=/opt/roundup/bin
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.
172 Configuring your first tracker
173 ------------------------------
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":
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::
183 mkdir /opt/roundup/trackers
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.
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)::
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
202 Note: "Back ends" selection list depends on availability of
203 third-party database modules. Standard python distribution
204 includes anydbm module only.
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.
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`_.
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::
221 web = http://localhost:8080/support/
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.
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::
233 Admin Password:
234 Confirm:
236 Note: running this command will *destroy any existing data in the
237 database*. In the case of MySQL and PostgreSQL, any exsting database
238 will be dropped and re-created.
240 Once this is done, the tracker has been created.
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::
248 roundup-server support=/opt/roundup/trackers/support
250 then direct your web browser at:
252 http://localhost:8080/support/
254 and you should see the tracker interface.
257 Choosing Your Template
258 ----------------------
260 Classic Template
261 ~~~~~~~~~~~~~~~~
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.
267 Minimal Template
268 ~~~~~~~~~~~~~~~~
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.
276 Choosing Your Backend
277 ---------------------
279 The actual storage of Roundup tracker information is handled by backends.
280 There's several to choose from, each with benefits and limitations:
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 ========== =========== ===== ==============================
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.
297 SQLite is supported via PySQLite versions 1.1.7, 2.1.0 and sqlite3 (the last
298 being bundled with Python 2.5+)
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``
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`_.
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.
323 Configure a Web Interface
324 -------------------------
326 There are five web interfaces to choose from:
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`_
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`_.
340 Web Server cgi-bin
341 ~~~~~~~~~~~~~~~~~~
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.
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.
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)::
353 adsutil.vbs set w3svc/AllowPathInfoForScriptMappings TRUE
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.
359 More information about ISS setup may be found at:
361 http://support.microsoft.com/default.aspx?scid=kb%3Ben-us%3B276494
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:
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)
371 Directly in the ``roundup.cgi`` file itself
372 Add your instance to the TRACKER_HOMES variable as ``'name': 'home'``
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.
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::
386 <Location /path/to/roundup>
387 SetHandler cgi-script
388 </Location>
391 CGI-bin for Limited-Access Hosting
392 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
398 1. Install flup_
399 2. Create a script ``roundup_stub`` in your server's ``cgi-bin`` directory
400 containing::
402 #!/usr/bin/env python
404 # if necessary modify the Python path to include the place you
405 # installed Roundup
406 #import sys
407 #sys.path.append('...')
409 # cgitb is needed for debugging in browser only
410 #import cgitb
411 #cgitb.enable()
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)
418 from flup.server.cgi import WSGIServer
419 WSGIServer(app).run()
421 3. Modify or created the ``.htaccess`` file in the desired (sub-)domain
422 directory to contain::
424 RewriteEngine On
425 RewriteBase /
426 RewriteRule ^(.*)$ /cgi-bin/roundup_stub/$1 [L]
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.
433 Stand-alone Web Server
434 ~~~~~~~~~~~~~~~~~~~~~~
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.
440 The stand-alone web server is started with the command ``roundup-server``. It
441 has several options - display them with ``roundup-server -h``.
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.
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.
451 Zope Product - ZRoundup
452 ~~~~~~~~~~~~~~~~~~~~~~~
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.
458 When you next (re)start up Zope, you will be able to add a ZRoundup object
459 that interfaces to your new tracker.
461 Apache HTTP Server with mod_python
462 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
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.
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/``)::
478 LD_PRELOAD=/lib/libpthread.so.0
479 export LD_PRELOAD
481 Example for FreeBSD (``envvars`` is in ``/usr/local/sbin/``)::
483 LD_PRELOAD=/usr/lib/libc_r.so
484 export LD_PRELOAD
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:
490 TrackerHome:
491 defines the tracker home directory - the directory that was specified
492 when you did ``roundup-admin init``. This option is required.
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.
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.
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.
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).
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.
532 Example mod_python configuration::
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>
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.
570 On Windows the corresponding lines will look similar to these::
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>
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!)
582 The URL for accessing these trackers then become:
583 `http://<roundupserver>/roundup/support/`` and
584 ``http://<roundupserver>/roundup/devel/``
586 Note that in order to use https connections you must set up Apache for secure
587 serving with SSL.
589 WSGI Handler
590 ~~~~~~~~~~~~
592 The WSGI handler is quite simple. The following sample code shows how
593 to use it::
595 from wsgiref.simple_server import make_server
597 # obtain the WSGI request dispatcher
598 from roundup.cgi.wsgi_handler import RequestDispatcher
599 tracker_home = 'demo'
600 app = RequestDispatcher(tracker_home)
602 httpd = make_server('', 8917, app)
603 httpd.serve_forever()
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/".
609 Configure an Email Interface
610 ----------------------------
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.
615 See `platform-specific notes`_ for steps that may be needed on your system.
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:
621 As a mail alias pipe process
622 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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).
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::
633 |roundup-mailgw /opt/roundup/trackers/support
635 To test the mail gateway on unix systems, try::
637 echo test |mail -s '[issue] test' support@YOUR_DOMAIN_HERE
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.*
644 As a custom router/transport using a pipe process (Exim4 specific)
645 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
652 .. _Exim 4: http://www.exim.org/
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.
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``.
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`_).
671 The matching is done in the line::
673 require_files = /usr/bin/roundup-mailgw:ROUNDUP_HOME/$local_part/schema.py
675 The following configuration has been tested on Debian Sarge with
676 Exim4.
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.
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.
691 This config makes a few assumptions:
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``.
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'.
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``).
706 Macros for Roundup router/transport. Should be placed in the macros
707 section of the Exim4 config::
709 # Home dir for your Roundup installation
710 ROUNDUP_HOME=/var/lib/roundup/trackers
712 # User and group for Roundup.
713 ROUNDUP_USER=roundup
714 ROUNDUP_GROUP=roundup
716 Custom router for Roundup. This will (probably) work if placed at the
717 beginning of the router section of the Exim4 config::
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
727 Custom transport for Roundup. This will (probably) work if placed at
728 the beginning of the router section of the Exim4 config::
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
738 As a regular job using a mailbox source
739 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
741 Set ``roundup-mailgw`` up to run every 10 minutes or so. For example
742 (substitute ``/usr/bin`` for wherever roundup-mailgw is installed)::
744 0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support mailbox <mail_spool_file>
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``".
750 As a regular job using a POP source
751 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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)::
757 0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support pop <pop_spec>
759 where pop_spec is "``username:password@server``" that specifies the roundup
760 submission user's POP account name, password and server.
762 On windows, you would set up the command using the windows scheduler.
764 As a regular job using an IMAP source
765 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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)::
771 0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support imap <imap_spec>
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``".
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.
781 As with the POP job, on windows, you would set up the command using the
782 windows scheduler.
785 UNIX Environment Steps
786 ----------------------
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::
800 support:*:1002:jblaine,samh,geezer,mail
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::
806 support:*:1002:jblaine,samh,geezer,mail,apache
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.
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``.
818 An alternative to the above is to create a new user who has the sole
819 responsibility of running roundup. This user:
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.
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.
834 Additional Language Codecs
835 --------------------------
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/
842 Public Tracker Considerations
843 -----------------------------
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.
848 The `customisation documentation`_ has a simple detector that will block
849 a lot of spam attempts. Look for the example "Preventing SPAM".
852 Maintenance
853 ===========
855 Read the separate `administration guide`_ for information about how to
856 perform common maintenance tasks with Roundup.
859 Upgrading
860 =========
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.
867 Further Reading
868 ===============
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`_.
875 Running Multiple Trackers
876 =========================
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.
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`_.
892 Platform-Specific Notes
893 =======================
895 Windows command-line tools
896 --------------------------
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.
901 On Windows 2000 and later:
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.
911 Where <dir> in 7) is the root directory (e.g., ``C:\Python22\Scripts``)
912 of your Python installation.
914 I understand that in XP, 2) above is not needed as "Control
915 Panel" is directly accessible from "Start".
917 I do not believe this is possible to do in previous versions of Windows.
920 Windows Server
921 --------------
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.
927 1. Using the Windows scheduler
928 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
930 Set up the following in Scheduled Tasks (note, the following is for a
931 cygwin setup):
933 **Run**
935 ``c:\cygwin\bin\bash.exe -c "roundup-server TheProject=/opt/roundup/trackers/support"``
937 **Start In**
939 ``C:\cygwin\opt\roundup\bin``
941 **Schedule**
943 At System Startup
945 To have the Roundup mail gateway run periodically to poll a POP email address,
946 set up the following in Scheduled Tasks:
948 **Run**
950 ``c:\cygwin\bin\bash.exe -c "roundup-mailgw /opt/roundup/trackers/support pop roundup:roundup@mail-server"``
952 **Start In**
954 ``C:\cygwin\opt\roundup\bin``
956 **Schedule**
958 Every 10 minutes from 5:00AM for 24 hours every day
960 Stop the task if it runs for 8 minutes
963 2. Installing the roundup server as a Windows service
964 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
970 For this you need first to create a service ini file containing the
971 relevant settings.
973 1. It is created if you execute the following command from within the
974 scripts directory (notice the use of backslashes)::
976 roundup-server -S -C <trackersdir>\server.ini -n <servername> -p 8080 -l <trackersdir>\trackerlog.log software=<trackersdir>\Software
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.
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::
986 [trackers]
987 software = C:\DATA\Roundup\Software
989 (this is an example where the tracker is named software and its home is
990 ``C:\DATA\Roundup\Software``)
992 3. Next give the commands that actually installs and starts the service::
994 roundup-server -C C:\DATA\Roundup\server.ini -c install
995 roundup-server -c start
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.
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.
1006 Sendmail smrsh
1007 --------------
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.
1013 This is usually done via the following 2 steps:
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.
1019 2. change your alias to ``"|roundup-mailgw <tracker_home>"``
1022 Linux
1023 -----
1025 Make sure you read the instructions under `UNIX environment steps`_.
1028 Solaris
1029 -------
1031 You'll need to build Python.
1033 Make sure you read the instructions under `UNIX environment steps`_.
1036 Problems? Testing your Python...
1037 ================================
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.
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.
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!
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.
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
1077 .. _External hyperlink targets:
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