1 ==================
2 Installing Roundup
3 ==================
5 :Version: $Revision: 1.60 $
7 .. contents::
10 Overview
11 ========
13 Broken out separately, there are several conceptual pieces to a
14 Roundup installation:
16 Roundup trackers
17 Trackers consist of issues (be they bug reports or otherwise), tracker
18 configuration file(s), web HTML files etc. Roundup trackers are initialised
19 with a "Template" which defines the fields usable/assignable on a
20 per-issue basis. Descriptions of the provided templates are given in
21 `choosing your template`_.
23 Roundup support code
24 Installed into your Python install's lib directory
26 Roundup scripts
27 These include the email gateway, the roundup
28 HTTP server, the roundup administration command-line interface, etc.
31 Prerequisites
32 =============
34 Python 2.1.1 or newer with a functioning anydbm or bsddb module. Download the
35 latest version from http://www.python.org/. It is highly recommended that
36 users install the latest patch version of python - 2.1.3 or 2.2.3 - as these
37 contain many fixes to serious bugs. Python 2.3 (currently in beta) has some
38 "issues", at least with the SQLite backend, and possibly with other backends
39 as well. It shouldn't be used with Roundup for now.
41 If you want to use Berkeley DB bsddb3 with Roundup, use version 3.3.0 or
42 later. Download the latest version from http://pybsddb.sourceforge.net/.
44 If you're on windows, you will either need to be using the ActiveState python
45 distribution (at http://www.activestate.com/Products/ActivePython/), or you'll
46 have to install the win32all package separately (get it from
47 http://starship.python.net/crew/mhammond/win32/).
50 Getting Roundup
51 ===============
53 Download the latest version from http://roundup.sf.net/.
55 Testing your Python
56 -------------------
58 Once you've unpacked roundup's source, run ``python ./run_tests`` in the
59 source directory and make sure there are no errors.
60 If there are errors, please let us know!
62 If the above fails, you may be using the wrong version of python. Try
63 ``python2 ./run_tests``. If that works, you will need to substitute
64 ``python2`` for ``python`` in all further commands you use in relation to
65 Roundup -- from installation and scripts.
68 For The Really Impatient
69 ========================
71 If you just want to give Roundup a whirl Right Now, then simply run
72 ``python demo.py``. This will set up a simple demo tracker on your
73 machine. When it's done, it'll print out a URL to point your web browser
74 at so you may start playing. Three users will be set up:
76 1. anonymous - the "default" user with permission to do very little
77 2. demo (password "demo") - a normal user who may create issues
78 3. admin (password "admin") - an administrative user who has complete
79 access to the tracker
82 Installation
83 ============
85 Note: some systems, such as Debian and NetBSD, already have Roundup
86 installed. Try running the command "roundup-admin" with no arguments,
87 and if it runs you may skip the `Basic Installation Steps`_
88 below.
90 Set aside 15-30 minutes. Please make sure you're using a supported version of
91 Python -- see `testing your python`_. There's several steps to follow in your
92 installation:
94 1. `basic installation steps`_ if Roundup is not installed on your system
95 2. `configuring your first tracker`_ that all installers must follow
96 3. then optionally `configure a web interface`_
97 4. and optionally `configure an email interface`_
98 5. `shared environment steps`_ to take if you're installing on a shared
99 UNIX machine and want to restrict local access to roundup
102 Basic Installation Steps
103 ------------------------
105 To install the Roundup support code into your Python tree and
106 Roundup scripts into /usr/local/bin (substitute that path for whatever is
107 appropriate on your system). You need to have write permissions
108 for these locations, eg. being root on unix::
110 python setup.py install
112 If you would like to place the Roundup scripts in a directory other
113 than ``/usr/local/bin``, then specify the preferred location with
114 ``--install-script``. For example, to install them in
115 ``/opt/roundup/bin``::
117 python setup.py install --install-scripts=/opt/roundup/bin
119 You can also use the ``--prefix`` option to use a completely different
120 base directory, if you do not want to use administrator rights. If you
121 choose to do this, take note of the message at the end of installation
122 and modify the python path accordingly.
125 Configuring your first tracker
126 ------------------------------
128 1. To create a Roundup tracker (necessary to do before you can
129 use the software in any real fashion), you need to set up a "tracker
130 home":
132 a. (Optional) If you intend to keep your roundup trackers
133 under one top level directory which does not exist yet,
134 you should create that directory now. Example::
136 mkdir /opt/roundup/trackers
138 b. Either add the Roundup script location to your ``PATH``
139 environment variable or specify the full path to
140 the command in the next step.
142 c. Install a new tracker with the command ``roundup-admin install``.
143 You will be asked a series of questions. Descriptions of the provided
144 templates can be found in `choosing your template`_ below. Descriptions
145 of the available backends can be found in `choosing your backend`_
146 below. The questions will be something like (you may have more
147 templates or backends available)::
149 Enter tracker home: /opt/roundup/trackers/support
150 Templates: classic
151 Select template [classic]: classic
152 Back ends: anydbm, bsddb
153 Select backend [anydbm]: anydbm
155 The "support" part of the tracker name can be anything you want - it
156 is going to be used as the directory that the tracker information
157 will be stored in.
159 You will now be directed to edit the tracker configuration and
160 initial schema. At a minimum, you must set ``MAILHOST``,
161 ``TRACKER_WEB``, ``MAIL_DOMAIN`` and ``ADMIN_EMAIL``. Note that the
162 configuration file uses Python syntax, so almost every value must be
163 ``'quoted'`` using single or double quotes. If you get stuck, and get
164 configuration file errors, then see the `tracker configuration`_ section
165 of the `customisation documentation`_.
167 If you just want to get set up to test things quickly (and follow
168 the instructions in step 3 below), you can even just set the
169 TRACKER_WEB variable to::
171 TRACKER_WEB = 'http://localhost:8080/support/'
173 The URL *must* end in a '/', or your web interface *will not work*.
174 See `Customising Roundup`_ for details on configuration and schema
175 changes. Note that you may change any of the configuration after
176 you've initialised the tracker - it's just better to have valid values
177 for this stuff now.
179 d. Initialise the tracker database with ``roundup-admin initialise``.
180 You will need to supply an admin password at this step. You will be
181 prompted::
183 Admin Password:
184 Confirm:
186 Once this is done, the tracker has been created.
188 2. At this point, your tracker is set up, but doesn't have a nice user
189 interface. To set that up, we need to `configure a web interface`_ and
190 optionally `configure an email interface`_. If you want to try your
191 new tracker out, assuming ``TRACKER_WEB`` is set to
192 ``'http://localhost:8080/support/'``, run::
194 roundup-server support=/opt/roundup/trackers/support
196 then direct your web browser at:
198 http://localhost:8080/support/
200 and you should see the tracker interface.
203 Choosing Your Template
204 ----------------------
206 Classic Template
207 ~~~~~~~~~~~~~~~~
209 The classic template is the one defined in the `Roundup Specification`_. It
210 holds issues which have priorities and statuses. Each issue may also have a
211 set of messages which are disseminated to the issue's list of nosy users.
213 Minimal Template
214 ~~~~~~~~~~~~~~~~
216 The minimal template has the minimum setup required for a tracker
217 installation. That is, it has the configuration files, defines a user database
218 and the basic HTML interface to that. It's a completely clean slate for you to
219 create your tracker on.
222 Choosing Your Backend
223 ---------------------
225 The actual storage of Roundup tracker information is handled by backends.
226 There's several to choose from, each with benefits and limitations:
228 **anydbm**
229 This backend is guaranteed to work on any system that Python runs on. It
230 will generally choose the best dbm backend that is available on your system
231 (from the list dbhash, gdbm, dbm, dumbdbm). It is the least scaleable of all
232 backends, but performs well enough for a smallish tracker (a couple of
233 thousand issues, under fifty users, ...).
234 **bsddb**
235 This effectively the same as anydbm, but uses the bsddb backend. This allows
236 it to gain some performance and scaling benefits.
237 **bsddb3**
238 Again, this effectively the same as anydbm, but uses the bsddb3 backend.
239 This allows it to gain some performance and scaling benefits.
240 **sqlite**
241 This uses the SQLite_ embedded RDBMS to provide a fast, scaleable backend.
242 There are no limitations, and it's much faster and more scaleable than the
243 dbm backends.
244 **mysql**
245 Backend for popular RDBMS MySQL. According to benchmarks, this backend works
246 much faster than any of \*dbm ones, but slightly slower than metakit and
247 sqlite. Scalability is unknown at present. Roundup requires InnoDB or BDB
248 support in MySQL. For more info on requirements and installation see
249 `additional mysql documentation`_ (doc/mysql.txt)
250 **metakit**
251 This backend is implemented over the metakit_ storage system, using Mk4Py as
252 the interface. It scales much better than the dbm backends.
254 You should be wary of using all but the mysql backend with high-volume trackers
255 (requests every second or two) as database locking is done on the whole
256 database.
258 You may set your tracker up with the anydbm backend (which is guaranteed to be
259 available) and switch to one of the other backends at any time using the
260 instructions in the `maintenance documentation`_.
263 Configure a Web Interface
264 -------------------------
266 There are three web interfaces to choose from:
268 1. `web server cgi-bin`_
269 2. `stand-alone web server`_
270 3. `Zope product - ZRoundup`_
272 You may need to give the web server user permission to access the tracker home
273 - see the `shared environment steps`_ for information. You may also need to
274 configure your system in some way - see `platform-specific notes`_.
277 Web Server cgi-bin
278 ~~~~~~~~~~~~~~~~~~
280 A benefit of using the cgi-bin approach is that it's the easiest way to
281 restrict access to your tracker to only use HTTPS. Access will be slower
282 than through the `stand-alone web server`_ though.
284 Note that if your Python isn't install as "python" then you'll need to edit
285 the ``roundup.cgi`` script to fix the first line.
287 If you're using IIS on a Windows platform, you'll need to run this command
288 for the cgi to work (it turns on the PATH_INFO cgi variable)::
290 adsutil.vbs set w3svc/AllowPathInfoForScriptMappings TRUE
292 The ``adsutil.vbs`` file can be found in either ``c:\inetpub\adminscripts``
293 or ``c:\winnt\system32\inetsrv\adminsamples\`` or
294 ``c:\winnt\system32\inetsrv\adminscripts\`` depending on your installation.
296 Copy the ``cgi-bin/roundup.cgi`` file to your web server's ``cgi-bin``
297 directory. You will need to configure it to tell it where your tracker home
298 is. You can do this either:
300 through an environment variable
301 set the variable TRACKER_HOMES to be a colon (":") separated list of
302 name=home pairs (if you're using apache, the SetEnv directive can do this)
303 directly in the ``roundup.cgi`` file itself
304 add your instance to the TRACKER_HOMES variable as ``'name': 'home'``
306 The "name" part of the configuration will appear in the URL and identifies the
307 tracker (so you may have more than one tracker per cgi-bin script). Make sure
308 there are no spaces or other illegal characters in it (to be safe, stick to
309 letters and numbers). The "name" forms part of the URL that appears in the
310 tracker config TRACKER_WEB variable, so make sure they match. The "home"
311 part of the configuration is the tracker home directory.
313 Stand-alone Web Server
314 ~~~~~~~~~~~~~~~~~~~~~~
316 This approach will give you the fastest of the three web interfaces. You may
317 investigate using ProxyPass or similar configuration in apache to have your
318 tracker accessed through the same URL as other systems.
320 The stand-alone web server is started with the command ``roundup-server``. It
321 has several options - display them with ``roundup-server -h``.
323 The tracker home configuration is similar to the cgi-bin - you may either edit
324 the script to change the TRACKER_HOMES variable or you may supply the
325 name=home values on the command-line after all the other options.
327 To make the server run in the background, use the "-d" option, specifying the
328 name of a file to write the server process id (pid) to.
330 To run the server proxied through apache (to take advantage of SSL or other
331 apache features), use the following configuration lines::
333 LoadModule proxy_module libexec/apache2/mod_proxy.so
334 LoadModule proxy_connect_module libexec/apache2/mod_proxy_connect.so
335 LoadModule proxy_http_module libexec/apache2/mod_proxy_http.so
337 <Location /prometheus/>
338 ProxyPass http://192.168.1.2:9090/roundup/
339 AuthType Basic
340 AuthName Roundup
341 AuthUserFile /some/place/htpasswd
342 Require valid-user
343 </Location>
345 Changing the ProxyPass line to point to the server you're running.
348 Zope Product - ZRoundup
349 ~~~~~~~~~~~~~~~~~~~~~~~
351 ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
352 your Products directory either in INSTANCE_HOME/Products or the Zope
353 code tree lib/python/Products.
355 When you next (re)start up Zope, you will be able to add a ZRoundup object
356 that interfaces to your new tracker.
359 Configure an Email Interface
360 ----------------------------
362 If you don't want to use the email component of Roundup, then remove the
363 "``nosyreaction.py``" module from your tracker "``detectors``" directory.
365 See `platform-specific notes`_ for steps that may be needed on your system.
367 There are three supported ways to get emailed issues into the
368 Roundup tracker. You should pick ONE of the following, all
369 of which will continue my example setup from above:
371 As a mail alias pipe process
372 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
374 Set up a mail alias called "issue_tracker" as (include the quote marks):
375 "``|/usr/bin/python /usr/local/bin/roundup-mailgw <tracker_home>``"
377 In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh so
378 sendmail will accept the pipe command. In that case, symlink
379 ``/etc/smrsh/roundup-mailgw`` to "``/usr/local/bin/roundup-mailgw``" and change
380 the command to::
382 |roundup-mailgw /opt/roundup/trackers/support
384 To test the mail gateway on unix systems, try::
386 echo test |mail -s '[issue] test' support@YOUR_DOMAIN_HERE
388 As a regular job using a mailbox source
389 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
391 Set ``roundup-mailgw`` up to run every 10 minutes or so. For example::
393 10 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support mailbox <mail_spool_file>
395 Where the ``mail_spool_file`` argument is the location of the roundup submission
396 user's mail spool. On most systems, the spool for a user "issue_tracker"
397 will be "``/var/mail/issue_tracker``".
399 As a regular job using a POP source
400 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
402 To retrieve from a POP mailbox, use a *cron* entry to the mailbox one::
404 10 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support pop <pop_spec>
406 where pop_spec is "``username:password@server``" that specifies the roundup
407 submission user's POP account name, password and server.
409 On windows, you would set up the command using the windows scheduler.
412 Shared Environment Steps
413 ------------------------
415 Each tracker ideally should have its own UNIX group, so create
416 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
417 you're using NIS). To continue with my examples so far, I would
418 create the UNIX group 'support', although the name of the UNIX
419 group does not have to be the same as the tracker name. To this
420 'support' group I then add all of the UNIX usernames who will be
421 working with this Roundup tracker. In addition to 'real' users,
422 the Roundup email gateway will need to have permissions to this
423 area as well, so add the user your mail service runs as to the
424 group (typically "mail" or "daemon"). The UNIX group might then
425 look like::
427 support:*:1002:jblaine,samh,geezer,mail
429 If you intend to use the web interface (as most people do), you
430 should also add the username your web server runs as to the group.
431 My group now looks like this::
433 support:*:1002:jblaine,samh,geezer,mail,apache
435 The tracker "db" directory should be chmod'ed g+sw so that the group can
436 write to the database, and any new files created in the database will be owned
437 by the group.
439 An alternative to the above is to create a new user who has the sole
440 responsibility of running roundup. This user:
442 1. runs the CGI interface daemon
443 2. runs regular polls for email
444 3. runs regular checks (using cron) to ensure the daemon is up
445 4. optionally has no login password so that nobody but the "root" user
446 may actually login and play with the roundup setup.
449 Maintenance
450 ===========
452 Read the separate `maintenance documentation`_ for information about how to
453 perform common maintenance tasks with Roundup.
456 Upgrading
457 =========
459 Read the separate `upgrading document`_, which describes the steps needed to
460 upgrade existing tracker trackers for each version of Roundup that is
461 released.
464 Further Reading
465 ===============
467 If you intend to use Roundup with anything other than the defualt
468 templates, if you would like to hack on Roundup, or if you would
469 like implementation details, you should read `Customising Roundup`_.
472 Running Multiple Trackers
473 =========================
475 Things to think about before you jump off the deep end and install
476 multiple trackers, which involve additional URLs, user databases, email
477 addresses, databases to back up, etc.
479 1. Do you want a tracker per product you sell/support? You can just add
480 a new property to your issues called Product, and filter by that.
481 2. Do you want to track internal software development issues and customer
482 support issues separately? You can just set up an additiona "issue"
483 class called "cust_issues" in the same tracker, mimicing the normal
484 "issue" class, but with different properties.
487 Platform-Specific Notes
488 =======================
490 Windows command-line tools
491 --------------------------
493 To make the command-line tools accessible in Windows, you need to update
494 the "Path" environment variable in the Registry via a dialog box.
496 On Windows 2000 and later:
498 1) Press the "Start" button.
499 2) Choose "Settings"
500 3) Choose "Control Panel"
501 4) Choose "System"
502 5) Choose "Advanced"
503 6) Choose "Environmental Variables"
504 7) Add: "<dir>\Scripts" to the "Path" environmental variable.
506 Where <dir> in 7) is the root directory (e.g., ``C:\Python22\Scripts``)
507 of your Python installation.
509 I understand that in XP, 2) above is not needed as "Control
510 Panel" is directly accessible from "Start".
512 I do not believe this is possible to do in previous versions of Windows.
515 Windows Server
516 --------------
518 To have the Roundup web server start up when your machine boots up, set the
519 following up in Scheduled Tasks (note, the following is for a cygwin setup):
521 Run
522 ``c:\cygwin\bin\bash.exe -c "roundup-server TheProject=/opt/roundup/trackers/support"``
523 Start In
524 ``C:\cygwin\opt\roundup\bin``
525 Schedule
526 At System Startup
528 To have the Roundup mail gateway run periodically to poll a POP email address,
529 set the following up in Scheduled Tasks:
531 Run
532 ``c:\cygwin\bin\bash.exe -c "roundup-mailgw /opt/roundup/trackers/support pop roundup:roundup@mail-server"``
533 Start In
534 ``C:\cygwin\opt\roundup\bin``
535 Schedule
536 Every 10 minutes from 5:00AM for 24 hours every day
537 Stop the task if it runs for 8 minutes
540 Sendmail smrsh
541 --------------
543 If you use Sendmail's ``smrsh`` mechanism, you will need to tell
544 smrsh that roundup-mailgw is a valid/trusted mail handler
545 before it will work.
547 This is usually done via the following 2 steps:
549 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
550 which points to the full path of your actual ``roundup-mailgw``
551 script.
553 2. change your alias to ``"|roundup-mailgw <tracker_home>"``
556 Linux
557 -----
559 Make sure you read the instructions under `shared environment steps`_.
561 Python 2.1.1 as shipped with SuSE7.3 might be missing module
562 ``_weakref``.
565 Solaris
566 -------
568 You'll need to build Python.
570 Make sure you read the instructions under `shared environment steps`_.
572 -------------------------------------------------------------------------------
574 Back to `Table of Contents`_
576 Next: `User Guide`_
578 .. _`table of contents`: index.html
579 .. _`user guide`: user_guide.html
580 .. _`roundup specification`: spec.html
581 .. _`tracker configuration`: customizing.html#tracker-configuration
582 .. _`customisation documentation`: customizing.html
583 .. _`customising roundup`: customizing.html
584 .. _`upgrading document`: upgrading.html
585 .. _`maintenance documentation`: maintenance.html
586 .. _sqlite: http://www.hwaci.com/sw/sqlite/
587 .. _metakit: http://www.equi4.com/metakit/
588 .. _`additional mysql documentation`: doc/mysql.html