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 with a functioning anydbm
34 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. `stand-alone web server`_
330 3. `Zope product - ZRoundup`_
331 4. `Apache HTTP Server with mod_python`_
332 5. `WSGI handler`_
334 You may need to give the web server user permission to access the tracker home
335 - see the `UNIX environment steps`_ for information. You may also need to
336 configure your system in some way - see `platform-specific notes`_.
339 Web Server cgi-bin
340 ~~~~~~~~~~~~~~~~~~
342 A benefit of using the cgi-bin approach is that it's the easiest way to
343 restrict access to your tracker to only use HTTPS. Access will be slower
344 than through the `stand-alone web server`_ though.
346 If your Python isn't installed as "python" then you'll need to edit
347 the ``roundup.cgi`` script to fix the first line.
349 If you're using IIS on a Windows platform, you'll need to run this command
350 for the cgi to work (it turns on the PATH_INFO cgi variable)::
352 adsutil.vbs set w3svc/AllowPathInfoForScriptMappings TRUE
354 The ``adsutil.vbs`` file can be found in either ``c:\inetpub\adminscripts``
355 or ``c:\winnt\system32\inetsrv\adminsamples\`` or
356 ``c:\winnt\system32\inetsrv\adminscripts\`` depending on your installation.
358 More information about ISS setup may be found at:
360 http://support.microsoft.com/default.aspx?scid=kb%3Ben-us%3B276494
362 Copy the ``frontends/roundup.cgi`` file to your web server's ``cgi-bin``
363 directory. You will need to configure it to tell it where your tracker home
364 is. You can do this either:
366 Through an environment variable
367 Set the variable TRACKER_HOMES to be a colon (":") separated list of
368 name=home pairs (if you're using apache, the SetEnv directive can do this)
370 Directly in the ``roundup.cgi`` file itself
371 Add your instance to the TRACKER_HOMES variable as ``'name': 'home'``
373 The "name" part of the configuration will appear in the URL and identifies the
374 tracker (so you may have more than one tracker per cgi-bin script). Make sure
375 there are no spaces or other illegal characters in it (to be safe, stick to
376 letters and numbers). The "name" forms part of the URL that appears in the
377 tracker config "tracker :: web" variable, so make sure they match. The "home"
378 part of the configuration is the tracker home directory.
380 If you're using Apache, you can use an additional trick to hide the
381 ``.cgi`` extension of the cgi script. Place the ``roundup.cgi`` script
382 wherever you want it to be, rename it to just ``roundup``, and add a
383 couple lines to your Apache configuration::
385 <Location /path/to/roundup>
386 SetHandler cgi-script
387 </Location>
390 Stand-alone Web Server
391 ~~~~~~~~~~~~~~~~~~~~~~
393 This approach will give you faster response than cgi-bin. You may
394 investigate using ProxyPass or similar configuration in apache to have your
395 tracker accessed through the same URL as other systems.
397 The stand-alone web server is started with the command ``roundup-server``. It
398 has several options - display them with ``roundup-server -h``.
400 The tracker home configuration is similar to the cgi-bin - you may either edit
401 the script to change the TRACKER_HOMES variable or you may supply the
402 name=home values on the command-line after all the other options.
404 To make the server run in the background, use the "-d" option, specifying the
405 name of a file to write the server process id (pid) to.
408 Zope Product - ZRoundup
409 ~~~~~~~~~~~~~~~~~~~~~~~
411 ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
412 your Products directory either in INSTANCE_HOME/Products or the Zope
413 code tree lib/python/Products.
415 When you next (re)start up Zope, you will be able to add a ZRoundup object
416 that interfaces to your new tracker.
418 Apache HTTP Server with mod_python
419 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
421 `Mod_python`_ is an `Apache`_ module that embeds the Python interpreter
422 within the server. Running Roundup this way is much faster than all
423 above options and, like `web server cgi-bin`_, allows you to use HTTPS
424 protocol. The drawback is that this setup is more complicated.
426 The following instructions were tested on apache 2.0 with mod_python 3.1.
427 If you are using older versions, your mileage may vary.
429 Mod_python uses OS threads. If your apache was built without threads
430 (quite commonly), you must load the threading library to run mod_python.
431 This is done by setting ``LD_PRELOAD`` to your threading library path
432 in apache ``envvars`` file. Example for gentoo linux (``envvars`` file
433 is located in ``/usr/lib/apache2/build/``)::
435 LD_PRELOAD=/lib/libpthread.so.0
436 export LD_PRELOAD
438 Example for FreeBSD (``envvars`` is in ``/usr/local/sbin/``)::
440 LD_PRELOAD=/usr/lib/libc_r.so
441 export LD_PRELOAD
443 Next, you have to add Roundup trackers configuration to apache config.
444 Roundup apache interface uses two options specified with ``PythonOption``
445 directives:
447 TrackerHome:
448 defines the tracker home directory - the directory that was specified
449 when you did ``roundup-admin init``. This option is required.
451 TrackerLaguage:
452 defines web user interface language. mod_python applications do not
453 receive OS environment variables in the same way as command-line
454 programs, so the language cannot be selected by setting commonly
455 used variables like ``LANG`` or ``LC_ALL``. ``TrackerLanguage``
456 value has the same syntax as values of these environment variables.
457 This option may be omitted.
459 TrackerDebug:
460 run the tracker in debug mode. Setting this option to ``yes`` or
461 ``true`` has the same effect as running ``roundup-server -t debug``:
462 the database schema and used html templates are rebuilt for each
463 HTTP request. Values ``no`` or ``false`` mean that all html
464 templates for the tracker are compiled and the database schema is
465 checked once at startup. This is the default behaviour.
467 TrackerTiming:
468 has nearly the same effect as environment variable ``CGI_SHOW_TIMING``
469 for standalone roundup server. The difference is that setting this
470 option to ``no`` or ``false`` disables timings display. Value
471 ``comment`` writes request handling times in html comment, and
472 any other non-empty value makes timing report visible. By default,
473 timing display is disabled.
475 In the following example we have two trackers set up in
476 ``/var/db/roundup/support`` and ``/var/db/roundup/devel`` and accessed
477 as ``https://my.host/roundup/support/`` and ``https://my.host/roundup/devel/``
478 respectively (provided Apache has been set up for SSL of course).
479 Having them share same parent directory allows us to
480 reduce the number of configuration directives. Support tracker has
481 russian user interface. The other tracker (devel) has english user
482 interface (default).
484 Static files from ``html`` directory are served by apache itself - this
485 is quickier and generally more robust than doing that from python.
486 Everything else is aliased to dummy (non-existing) ``py`` file,
487 which is handled by mod_python and our roundup module.
489 Example mod_python configuration::
491 #################################################
492 # Roundup Issue tracker
493 #################################################
494 # enable Python optimizations (like 'python -O')
495 PythonOptimize On
496 # let apache handle static files from 'html' directories
497 AliasMatch /roundup/(.+)/@@file/(.*) /var/db/roundup/$1/html/$2
498 # everything else is handled by roundup web UI
499 AliasMatch /roundup/([^/]+)/(?!@@file/)(.*) /var/db/roundup/$1/dummy.py/$2
500 # roundup requires a slash after tracker name - add it if missing
501 RedirectMatch permanent ^/roundup/([^/]+)$ /roundup/$1/
502 # common settings for all roundup trackers
503 <Directory /var/db/roundup/*>
504 Order allow,deny
505 Allow from all
506 AllowOverride None
507 Options None
508 AddHandler python-program .py
509 PythonHandler roundup.cgi.apache
510 # uncomment the following line to see tracebacks in the browser
511 # (note that *some* tracebacks will be displayed anyway)
512 #PythonDebug On
513 </Directory>
514 # roundup tracker homes
515 <Directory /var/db/roundup/support>
516 PythonOption TrackerHome /var/db/roundup/support
517 PythonOption TrackerLanguage ru
518 </Directory>
519 <Directory /var/db/roundup/devel>
520 PythonOption TrackerHome /var/db/roundup/devel
521 </Directory>
523 Notice that the ``/var/db/roundup`` path shown above refers to the directory
524 in which the tracker homes are stored. The actual value will thus depend on
525 your system.
527 On Windows the corresponding lines will look similar to these::
529 AliasMatch /roundup/(.+)/@@file/(.*) C:/DATA/roundup/$1/html/$2
530 AliasMatch /roundup/([^/]+)/(?!@@file/)(.*) C:/DATA/roundup/$1/dummy.py/$2
531 <Directory C:/DATA/roundup/*>
532 <Directory C:/DATA/roundup/support>
533 <Directory C:/DATA/roundup/devel>
535 In this example the directory hosting all of the tracker homes is
536 ``C:\DATA\roundup``. (Notice that you must use forward slashes in paths
537 inside the httpd.conf file!)
539 The URL for accessing these trackers then become:
540 `http://<roundupserver>/roundup/support/`` and
541 ``http://<roundupserver>/roundup/devel/``
543 Note that in order to use https connections you must set up Apache for secure
544 serving with SSL.
546 WSGI Handler
547 ~~~~~~~~~~~~
549 The WSGI handler is quite simple. The following sample code shows how
550 to use it::
552 from wsgiref.simple_server import make_server
554 # obtain the WSGI request dispatcher
555 from roundup.cgi.wsgi_handler import RequestDispatcher
556 tracker_home = 'demo'
557 app = RequestDispatcher(tracker_home)
559 httpd = make_server('', 8917, app)
560 httpd.serve_forever()
562 To test the above you should create a demo tracker with ``python demo.py``.
563 Edit the ``config.ini`` to change the web URL to "http://localhost:8917/".
566 Configure an Email Interface
567 ----------------------------
569 If you don't want to use the email component of Roundup, then remove the
570 "``nosyreaction.py``" module from your tracker "``detectors``" directory.
572 See `platform-specific notes`_ for steps that may be needed on your system.
574 There are five supported ways to get emailed issues into the
575 Roundup tracker. You should pick ONE of the following, all
576 of which will continue my example setup from above:
578 As a mail alias pipe process
579 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
581 Set up a mail alias called "issue_tracker" as (include the quote marks):
582 "``|/usr/bin/python /usr/bin/roundup-mailgw <tracker_home>``"
583 (substitute ``/usr/bin`` for wherever roundup-mailgw is installed).
585 In some installations (e.g. RedHat Linux and Fedora Core) you'll need to
586 set up smrsh so sendmail will accept the pipe command. In that case,
587 symlink ``/etc/smrsh/roundup-mailgw`` to "``/usr/bin/roundup-mailgw``"
588 and change the command to::
590 |roundup-mailgw /opt/roundup/trackers/support
592 To test the mail gateway on unix systems, try::
594 echo test |mail -s '[issue] test' support@YOUR_DOMAIN_HERE
596 Be careful that some mail systems (postfix for example) will impost a
597 limits on processes they spawn. In particular postfix can set a file size
598 limit. *This can cause your Roundup database to become corrupted.*
601 As a custom router/transport using a pipe process (Exim4 specific)
602 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
604 The following configuration snippets for `Exim 4`_ configuration
605 implement a custom router & transport to accomplish mail delivery to
606 roundup-mailgw. A configuration for Exim3 is similar but not
607 included, since Exim3 is considered obsolete.
609 .. _Exim 4: http://www.exim.org/
611 This configuration is similar to the previous section, in that it uses
612 a pipe process. However, there are advantages to using a custom
613 router/transport process, if you are using Exim.
615 * This avoids privilege escalation, since otherwise the pipe process
616 will run as the mail user, typically mail. The transport can be
617 configured to run as the user appropriate for the task at hand. In the
618 transport described in this section, Exim4 runs as the unprivileged
619 user ``roundup``.
621 * Separate configuration is not required for each tracker
622 instance. When a email arrives at the server, Exim passes it through
623 the defined routers. The roundup_router looks for a match with one of
624 the roundup directories, and if there is one it is passed to the
625 roundup_transport, which uses the pipe process described in the
626 previous section (`As a mail alias pipe process`_).
628 The matching is done in the line::
630 require_files = /usr/bin/roundup-mailgw:ROUNDUP_HOME/$local_part/schema.py
632 The following configuration has been tested on Debian Sarge with
633 Exim4.
635 .. note::
636 Note that the Debian Exim4 packages don't allow pipes in alias files
637 by default, so the method described in the section `As a mail alias
638 pipe process`_ will not work with the default configuration. However,
639 the method described in this section does. See the discussion in
640 ``/usr/share/doc/exim4-config/README.system_aliases`` on any Debian
641 system with Exim4 installed.
643 For more Debian-specific information, see suggested addition to
644 README.Debian in
645 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=343283, which will
646 hopefully be merged into the Debian package eventually.
648 This config makes a few assumptions:
650 * That the mail address corresponding to the tracker instance has the
651 same name as the directory of the tracker instance, i.e. the mail
652 interface address corresponding to a Roundup instance called
653 ``/var/lib/roundup/trackers/mytracker`` is ``mytracker@your.host``.
655 * That (at least) all the db subdirectories of all the tracker
656 instances (ie. ``/var/lib/roundup/trackers/*/db``) are owned by the same
657 user, in this case, 'roundup'.
659 * That if the ``schema.py`` file exists, then the tracker is ready for
660 use. Another option is to use the ``config.ini`` file (this changed
661 in 0.8 from ``config.py``).
663 Macros for Roundup router/transport. Should be placed in the macros
664 section of the Exim4 config::
666 # Home dir for your Roundup installation
667 ROUNDUP_HOME=/var/lib/roundup/trackers
669 # User and group for Roundup.
670 ROUNDUP_USER=roundup
671 ROUNDUP_GROUP=roundup
673 Custom router for Roundup. This will (probably) work if placed at the
674 beginning of the router section of the Exim4 config::
676 roundup_router:
677 driver = accept
678 # The config file config.ini seems like a more natural choice, but the
679 # file config.py was replaced by config.ini in 0.8, and schema.py needs
680 # to be present too.
681 require_files = /usr/bin/roundup-mailgw:ROUNDUP_HOME/$local_part/schema.py
682 transport = roundup_transport
684 Custom transport for Roundup. This will (probably) work if placed at
685 the beginning of the router section of the Exim4 config::
687 roundup_transport:
688 driver = pipe
689 command = /usr/bin/python /usr/bin/roundup-mailgw ROUNDUP_HOME/$local_part/
690 current_directory = ROUNDUP_HOME
691 home_directory = ROUNDUP_HOME
692 user = ROUNDUP_USER
693 group = ROUNDUP_GROUP
695 As a regular job using a mailbox source
696 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
698 Set ``roundup-mailgw`` up to run every 10 minutes or so. For example
699 (substitute ``/usr/bin`` for wherever roundup-mailgw is installed)::
701 0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support mailbox <mail_spool_file>
703 Where the ``mail_spool_file`` argument is the location of the roundup submission
704 user's mail spool. On most systems, the spool for a user "issue_tracker"
705 will be "``/var/mail/issue_tracker``".
707 As a regular job using a POP source
708 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
710 To retrieve from a POP mailbox, use a *cron* entry similar to the mailbox
711 one (substitute ``/usr/bin`` for wherever roundup-mailgw is
712 installed)::
714 0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support pop <pop_spec>
716 where pop_spec is "``username:password@server``" that specifies the roundup
717 submission user's POP account name, password and server.
719 On windows, you would set up the command using the windows scheduler.
721 As a regular job using an IMAP source
722 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
724 To retrieve from an IMAP mailbox, use a *cron* entry similar to the
725 POP one (substitute ``/usr/bin`` for wherever roundup-mailgw is
726 installed)::
728 0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support imap <imap_spec>
730 where imap_spec is "``username:password@server``" that specifies the roundup
731 submission user's IMAP account name, password and server. You may
732 optionally include a mailbox to use other than the default ``INBOX`` with
733 "``imap username:password@server mailbox``".
735 If you have a secure (ie. HTTPS) IMAP server then you may use ``imaps``
736 in place of ``imap`` in the command to use a secure connection.
738 As with the POP job, on windows, you would set up the command using the
739 windows scheduler.
742 UNIX Environment Steps
743 ----------------------
745 Each tracker ideally should have its own UNIX group, so create
746 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
747 you're using NIS). To continue with my examples so far, I would
748 create the UNIX group 'support', although the name of the UNIX
749 group does not have to be the same as the tracker name. To this
750 'support' group I then add all of the UNIX usernames who will be
751 working with this Roundup tracker. In addition to 'real' users,
752 the Roundup email gateway will need to have permissions to this
753 area as well, so add the user your mail service runs as to the
754 group (typically "mail" or "daemon"). The UNIX group might then
755 look like::
757 support:*:1002:jblaine,samh,geezer,mail
759 If you intend to use the web interface (as most people do), you
760 should also add the username your web server runs as to the group.
761 My group now looks like this::
763 support:*:1002:jblaine,samh,geezer,mail,apache
765 The tracker "db" directory should be chmod'ed g+sw so that the group can
766 write to the database, and any new files created in the database will be owned
767 by the group.
769 If you're using the mysql or postgresql backend then you'll need to ensure
770 that the tracker user has appropriate permissions to create/modify the
771 database. If you're using roundup.cgi, the apache user needs permissions
772 to modify the database. Alternatively, explicitly specify a database login
773 in ``rdbms`` -> ``user`` and ``password`` in ``config.ini``.
775 An alternative to the above is to create a new user who has the sole
776 responsibility of running roundup. This user:
778 1. runs the CGI interface daemon
779 2. runs regular polls for email
780 3. runs regular checks (using cron) to ensure the daemon is up
781 4. optionally has no login password so that nobody but the "root" user
782 may actually login and play with the roundup setup.
784 If you're using a Linux system (e.g. Fedora Core) with SELinux enabled,
785 you will need to ensure that the db directory has a context that
786 permits the web server to modify and create files. If you're using the
787 mysql or postgresql backend you may also need to update your policy to
788 allow the web server to access the database socket.
791 Additional Language Codecs
792 --------------------------
794 If you intend to send messages to Roundup that use Chinese, Japanese or
795 Korean encodings the you'll need to obtain CJKCodecs from
796 http://cjkpython.berlios.de/
799 Public Tracker Considerations
800 -----------------------------
802 If you run a public tracker, you will eventually have to think about
803 dealing with spam entered through both the web and mail interfaces.
805 The `customisation documentation`_ has a simple detector that will block
806 a lot of spam attempts. Look for the example "Preventing SPAM".
809 Maintenance
810 ===========
812 Read the separate `administration guide`_ for information about how to
813 perform common maintenance tasks with Roundup.
816 Upgrading
817 =========
819 Read the separate `upgrading document`_, which describes the steps needed to
820 upgrade existing tracker trackers for each version of Roundup that is
821 released.
824 Further Reading
825 ===============
827 If you intend to use Roundup with anything other than the default
828 templates, if you would like to hack on Roundup, or if you would
829 like implementation details, you should read `Customising Roundup`_.
832 Running Multiple Trackers
833 =========================
835 Things to think about before you jump off the deep end and install
836 multiple trackers, which involve additional URLs, user databases, email
837 addresses, databases to back up, etc.
839 1. Do you want a tracker per product you sell/support? You can just add
840 a new property to your issues called Product, and filter by that. See
841 the customisation example `adding a new field to the classic schema`_.
842 2. Do you want to track internal software development issues and customer
843 support issues separately? You can just set up an additional "issue"
844 class called "cust_issues" in the same tracker, mimicing the normal
845 "issue" class, but with different properties. See the customisation
846 example `tracking different types of issues`_.
849 Platform-Specific Notes
850 =======================
852 Windows command-line tools
853 --------------------------
855 To make the command-line tools accessible in Windows, you need to update
856 the "Path" environment variable in the Registry via a dialog box.
858 On Windows 2000 and later:
860 1) Press the "Start" button.
861 2) Choose "Settings"
862 3) Choose "Control Panel"
863 4) Choose "System"
864 5) Choose "Advanced"
865 6) Choose "Environmental Variables"
866 7) Add: "<dir>\Scripts" to the "Path" environmental variable.
868 Where <dir> in 7) is the root directory (e.g., ``C:\Python22\Scripts``)
869 of your Python installation.
871 I understand that in XP, 2) above is not needed as "Control
872 Panel" is directly accessible from "Start".
874 I do not believe this is possible to do in previous versions of Windows.
877 Windows Server
878 --------------
880 To have the Roundup web server start up when your machine boots up, there
881 are two different methods, the scheduler and installing the service.
884 1. Using the Windows scheduler
885 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
887 Set up the following in Scheduled Tasks (note, the following is for a
888 cygwin setup):
890 **Run**
892 ``c:\cygwin\bin\bash.exe -c "roundup-server TheProject=/opt/roundup/trackers/support"``
894 **Start In**
896 ``C:\cygwin\opt\roundup\bin``
898 **Schedule**
900 At System Startup
902 To have the Roundup mail gateway run periodically to poll a POP email address,
903 set up the following in Scheduled Tasks:
905 **Run**
907 ``c:\cygwin\bin\bash.exe -c "roundup-mailgw /opt/roundup/trackers/support pop roundup:roundup@mail-server"``
909 **Start In**
911 ``C:\cygwin\opt\roundup\bin``
913 **Schedule**
915 Every 10 minutes from 5:00AM for 24 hours every day
917 Stop the task if it runs for 8 minutes
920 2. Installing the roundup server as a Windows service
921 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
923 This is more Windows oriented and will make the Roundup server run as
924 soon as the PC starts up without any need for a login or such. It will
925 also be available in the normal Windows Administrative Tools.
927 For this you need first to create a service ini file containing the
928 relevant settings.
930 1. It is created if you execute the following command from within the
931 scripts directory (notice the use of backslashes)::
933 roundup-server -S -C <trackersdir>\server.ini -n <servername> -p 8080 -l <trackersdir>\trackerlog.log software=<trackersdir>\Software
935 where the item ``<trackersdir>`` is replaced with the physical directory
936 that hosts all of your trackers. The ``<servername>`` item is the name
937 of your roundup server PC, such as w2003srv or similar.
939 2. Next open the now created file ``C:\DATA\roundup\server.ini`` file
940 (if your ``<trackersdir>`` is ``C:\DATA\roundup``).
941 Check the entries for correctness, especially this one::
943 [trackers]
944 software = C:\DATA\Roundup\Software
946 (this is an example where the tracker is named software and its home is
947 ``C:\DATA\Roundup\Software``)
949 3. Next give the commands that actually installs and starts the service::
951 roundup-server -C C:\DATA\Roundup\server.ini -c install
952 roundup-server -c start
954 4. Finally open the AdministrativeTools/Services applet and locate the
955 Roundup service entry. Open its properties and change it to start
956 automatically instead of manually.
958 If you are using Apache as the webserver you might want to use it with
959 mod_python instead to serve out Roundup. In that case see the mod_python
960 instructions above for details.
963 Sendmail smrsh
964 --------------
966 If you use Sendmail's ``smrsh`` mechanism, you will need to tell
967 smrsh that roundup-mailgw is a valid/trusted mail handler
968 before it will work.
970 This is usually done via the following 2 steps:
972 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
973 which points to the full path of your actual ``roundup-mailgw``
974 script.
976 2. change your alias to ``"|roundup-mailgw <tracker_home>"``
979 Linux
980 -----
982 Make sure you read the instructions under `UNIX environment steps`_.
985 Solaris
986 -------
988 You'll need to build Python.
990 Make sure you read the instructions under `UNIX environment steps`_.
993 Problems? Testing your Python...
994 ================================
996 .. note::
997 The ``run_tests.py`` script is packaged in Roundup's source distribution
998 - users of the Windows installer, other binary distributions or
999 pre-installed Roundup will need to download the source to use it.
1001 Once you've unpacked roundup's source, run ``python run_tests.py`` in the
1002 source directory and make sure there are no errors. If there are errors,
1003 please let us know!
1005 If the above fails, you may be using the wrong version of python. Try
1006 ``python2 run_tests.py``. If that works, you will need to substitute
1007 ``python2`` for ``python`` in all further commands you use in relation to
1008 Roundup -- from installation and scripts.
1011 .. _`table of contents`: index.html
1012 .. _`user guide`: user_guide.html
1013 .. _`roundup specification`: spec.html
1014 .. _`tracker configuration`: customizing.html#tracker-configuration
1015 .. _`customisation documentation`: customizing.html
1016 .. _`Adding a new field to the classic schema`:
1017 customizing.html#adding-a-new-field-to-the-classic-schema
1018 .. _`Tracking different types of issues`:
1019 customizing.html#tracking-different-types-of-issues
1020 .. _`customising roundup`: customizing.html
1021 .. _`upgrading document`: upgrading.html
1022 .. _`administration guide`: admin_guide.html
1025 .. _External hyperlink targets:
1027 .. _apache: http://httpd.apache.org/
1028 .. _mod_python: http://www.modpython.org/
1029 .. _MySQLdb: http://sourceforge.net/projects/mysql-python
1030 .. _Psycopg: http://initd.org/software/initd/psycopg
1031 .. _pysqlite: http://pysqlite.org/