Code

more doc
[roundup.git] / doc / installation.txt
1 ==================
2 Installing Roundup
3 ==================
5 :Version: $Revision: 1.72 $
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 Roundup requires Python 2.1.3 or newer with a functioning anydbm or
35 bsddb module. Download the latest version from http://www.python.org/.
36 It is highly recommended that users install the latest patch version
37 of python as these contain many fixes to serious bugs.
39 If you want to use Berkeley DB bsddb3 with Roundup, use version 3.3.0 or
40 later. Download the latest version from http://pybsddb.sourceforge.net/.
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/).
47 Non-Python2.3 users may need to `install the "CSV" module`_.
49 Install the "CSV" module
50 ------------------------
52 Note: CSV stands for Comma-Separated-Value. These files are used by all
53       manner of programs (eg. spreadsheets) to exchange data.
55 The "CSV" module is required if you wish to import or export data in the
56 tracker, or if you wish to use the online generic class editing facility.
58 If you're using a version of Python older than 2.3, then you will need to
59 install the "CSV" module from `Object Craft`_. Users of Python2.3 and later
60 don't need to. If you have a C compiler installed, then download the source
61 and follow their installation instructions (simply ``python setup.py
62 install``.)
64 If you're on Windows and don't have a C compiler, then you'll need to
65 download the pre-compiled ``csv.pyd`` file and install it. To install, just
66 copy it to your Python installation in the ``lib\site-packages`` directory.
67 For Python 2.2, this would be::
69    c:\python22\lib\site-packages
71 Once the CSV module is installed, you *must* restart roundup-server if it
72 is already running, or the new module won't be detected.
74 If you're on some other platform and don't have a C compiler, you'll need
75 to ask for help on the roundup-users mailing list.
77 .. _`Object Craft`: http://object-craft.com.au/
80 Getting Roundup
81 ===============
83 Download the latest version from http://roundup.sf.net/.
85 Testing your Python
86 -------------------
88 Once you've unpacked roundup's source, run ``python run_tests.py`` in the
89 source directory and make sure there are no errors. If there are errors,
90 please let us know!
92 If the above fails, you may be using the wrong version of python. Try
93 ``python2 run_tests.py``. If that works, you will need to substitute
94 ``python2`` for ``python`` in all further commands you use in relation to
95 Roundup -- from installation and scripts.
98 For The Really Impatient
99 ========================
101 If you just want to give Roundup a whirl Right Now, then simply run
102 ``python demo.py``. This will set up a simple demo tracker on your
103 machine. When it's done, it'll print out a URL to point your web browser
104 at so you may start playing. Three users will be set up:
106 1. anonymous - the "default" user with permission to do very little
107 2. demo (password "demo") - a normal user who may create issues
108 3. admin (password "admin") - an administrative user who has complete
109    access to the tracker
112 Installation
113 ============
115 :Note: Some systems, such as Debian and NetBSD, already have Roundup
116        installed. Try running the command "roundup-admin" with no arguments,
117        and if it runs you may skip the `Basic Installation Steps`_
118        below and go straight to `configuring your first tracker`_.
120 Set aside 15-30 minutes. Please make sure you're using a supported version of
121 Python -- see `testing your python`_. There's several steps to follow in your
122 installation:
124 1. `basic installation steps`_ if Roundup is not installed on your system
125 2. `configuring your first tracker`_ that all installers must follow
126 3. then optionally `configure a web interface`_
127 4. and optionally `configure an email interface`_
128 5. `UNIX environment steps`_ to take if you're installing on a shared
129    UNIX machine and want to restrict local access to roundup
130 6. `additional language codecs`_
132 For information about how Roundup installs, see the `administration
133 guide`_.
136 Basic Installation Steps
137 ------------------------
139 To install the Roundup support code into your Python tree and
140 Roundup scripts into /usr/local/bin (substitute that path for whatever is
141 appropriate on your system). You need to have write permissions
142 for these locations, eg. being root on unix::
144     python setup.py install
146 If you would like to place the Roundup scripts in a directory other
147 than ``/usr/local/bin``, then specify the preferred location with
148 ``--install-script``. For example, to install them in
149 ``/opt/roundup/bin``::
151     python setup.py install --install-scripts=/opt/roundup/bin
153 You can also use the ``--prefix`` option to use a completely different
154 base directory, if you do not want to use administrator rights. If you
155 choose to do this, take note of the message at the end of installation
156 and modify the python path accordingly.
159 Configuring your first tracker
160 ------------------------------
162 1. To create a Roundup tracker (necessary to do before you can
163    use the software in any real fashion), you need to set up a "tracker
164    home":
166    a. (Optional) If you intend to keep your roundup trackers
167       under one top level directory which does not exist yet,
168       you should create that directory now.  Example::
170          mkdir /opt/roundup/trackers
172    b. Either add the Roundup script location to your ``PATH``
173       environment variable or specify the full path to
174       the command in the next step.
176    c. Install a new tracker with the command ``roundup-admin install``.
177       You will be asked a series of questions.  Descriptions of the provided
178       templates can be found in `choosing your template`_ below.  Descriptions
179       of the available backends can be found in `choosing your backend`_
180       below.  The questions will be something like (you may have more
181       templates or backends available)::
183           Enter tracker home: /opt/roundup/trackers/support
184           Templates: classic
185           Select template [classic]: classic
186           Back ends: anydbm, bsddb
187           Select backend [anydbm]: anydbm
189       The "support" part of the tracker name can be anything you want - it
190       is going to be used as the directory that the tracker information
191       will be stored in.
193       You will now be directed to edit the tracker configuration and
194       initial schema.  At a minimum, you must set ``MAILHOST``,
195       ``TRACKER_WEB``, ``MAIL_DOMAIN`` and ``ADMIN_EMAIL``. Note that the
196       configuration file uses Python syntax, so almost every value must be
197       ``'quoted'`` using single or double quotes. If you get stuck, and get
198       configuration file errors, then see the `tracker configuration`_ section
199       of the `customisation documentation`_.
201       If you just want to get set up to test things quickly (and follow
202       the instructions in step 3 below), you can even just set the
203       TRACKER_WEB variable to::
205          TRACKER_WEB = 'http://localhost:8080/support/'
207       The URL *must* end in a '/', or your web interface *will not work*.
208       See `Customising Roundup`_ for details on configuration and schema
209       changes. Note that you may change any of the configuration after
210       you've initialised the tracker - it's just better to have valid values
211       for this stuff now.
213    d. Initialise the tracker database with ``roundup-admin initialise``.
214       You will need to supply an admin password at this step. You will be
215       prompted::
217           Admin Password:
218                  Confirm:
220       Once this is done, the tracker has been created.
222 2. At this point, your tracker is set up, but doesn't have a nice user
223    interface. To set that up, we need to `configure a web interface`_ and
224    optionally `configure an email interface`_. If you want to try your
225    new tracker out, assuming ``TRACKER_WEB`` is set to
226    ``'http://localhost:8080/support/'``, run::
228      roundup-server support=/opt/roundup/trackers/support
230    then direct your web browser at:
232      http://localhost:8080/support/
234    and you should see the tracker interface.
237 Choosing Your Template
238 ----------------------
240 Classic Template
241 ~~~~~~~~~~~~~~~~
243 The classic template is the one defined in the `Roundup Specification`_. It
244 holds issues which have priorities and statuses. Each issue may also have a
245 set of messages which are disseminated to the issue's list of nosy users.
247 Minimal Template
248 ~~~~~~~~~~~~~~~~
250 The minimal template has the minimum setup required for a tracker
251 installation. That is, it has the configuration files, defines a user database
252 and the basic HTML interface to that. It's a completely clean slate for you to
253 create your tracker on.
256 Choosing Your Backend
257 ---------------------
259 The actual storage of Roundup tracker information is handled by backends.
260 There's several to choose from, each with benefits and limitations:
262 ========== =========== ===== ==============================
263 Name       Speed       Users   Support
264 ========== =========== ===== ==============================
265 anydbm     Slowest     Few   Always available
266 bsddb      Slow        Few   Usually available
267 sqlite     Fastest(*)  Few   Needs install (SQLite_)
268 metakit    Fastest(*)  Few   Needs install (metakit_)
269 postgresql Fast        Many  Needs install/admin (psycopg_)
270 mysql      Fast        Many  Needs install/admin (MySQLdb_)
271 ========== =========== ===== ==============================
273 **sqlite** and **metakit**
274   These use the embedded database engines SQLite_ and metakit_ to provide
275   very fast backends. They are not suitable for trackers which will have
276   many simultaneous users.
277 **postgresql**
278   Backend for popular RDBMS PostgreSQL. You must read doc/postgresql.txt for
279   additional installation steps and requirements.
280 **mysql**
281   Backend for popular RDBMS MySQL. You must read doc/mysql.txt for additional
282   installation steps and requirements.
284 You may defer your decision by setting your tracker up with the anydbm
285 backend (which is guaranteed to be available) and switching to one of the
286 other backends at any time using the instructions in the `administration
287 guide`_.
290 Configure a Web Interface
291 -------------------------
293 There are three web interfaces to choose from:
295 1. `web server cgi-bin`_
296 2. `stand-alone web server`_
297 3. `Zope product - ZRoundup`_
299 You may need to give the web server user permission to access the tracker home
300 - see the `UNIX environment steps`_ for information. You may also need to
301 configure your system in some way - see `platform-specific notes`_.
304 Web Server cgi-bin
305 ~~~~~~~~~~~~~~~~~~
307 A benefit of using the cgi-bin approach is that it's the easiest way to
308 restrict access to your tracker to only use HTTPS. Access will be slower
309 than through the `stand-alone web server`_ though.
311 Note that if your Python isn't install as "python" then you'll need to edit
312 the ``roundup.cgi`` script to fix the first line.
314 If you're using IIS on a Windows platform, you'll need to run this command
315 for the cgi to work (it turns on the PATH_INFO cgi variable)::
317     adsutil.vbs set w3svc/AllowPathInfoForScriptMappings TRUE
319 The ``adsutil.vbs`` file can be found in either ``c:\inetpub\adminscripts`` 
320 or ``c:\winnt\system32\inetsrv\adminsamples\`` or
321 ``c:\winnt\system32\inetsrv\adminscripts\`` depending on your installation.
323 Copy the ``cgi-bin/roundup.cgi`` file to your web server's ``cgi-bin``
324 directory. You will need to configure it to tell it where your tracker home
325 is. You can do this either:
327 through an environment variable
328  set the variable TRACKER_HOMES to be a colon (":") separated list of
329  name=home pairs (if you're using apache, the SetEnv directive can do this)
330 directly in the ``roundup.cgi`` file itself
331  add your instance to the TRACKER_HOMES variable as ``'name': 'home'``
333 The "name" part of the configuration will appear in the URL and identifies the
334 tracker (so you may have more than one tracker per cgi-bin script). Make sure
335 there are no spaces or other illegal characters in it (to be safe, stick to
336 letters and numbers). The "name" forms part of the URL that appears in the
337 tracker config TRACKER_WEB variable, so make sure they match. The "home"
338 part of the configuration is the tracker home directory.
340 Stand-alone Web Server
341 ~~~~~~~~~~~~~~~~~~~~~~
343 This approach will give you the fastest of the three web interfaces. You may
344 investigate using ProxyPass or similar configuration in apache to have your
345 tracker accessed through the same URL as other systems.
347 The stand-alone web server is started with the command ``roundup-server``. It
348 has several options - display them with ``roundup-server -h``.
350 The tracker home configuration is similar to the cgi-bin - you may either edit
351 the script to change the TRACKER_HOMES variable or you may supply the
352 name=home values on the command-line after all the other options.
354 To make the server run in the background, use the "-d" option, specifying the
355 name of a file to write the server process id (pid) to.
358 Zope Product - ZRoundup
359 ~~~~~~~~~~~~~~~~~~~~~~~
361 ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
362 your Products directory either in INSTANCE_HOME/Products or the Zope
363 code tree lib/python/Products.
365 When you next (re)start up Zope, you will be able to add a ZRoundup object
366 that interfaces to your new tracker.
369 Configure an Email Interface
370 ----------------------------
372 If you don't want to use the email component of Roundup, then remove the
373 "``nosyreaction.py``" module from your tracker "``detectors``" directory.
375 See `platform-specific notes`_ for steps that may be needed on your system.
377 There are three supported ways to get emailed issues into the
378 Roundup tracker.  You should pick ONE of the following, all
379 of which will continue my example setup from above:
381 As a mail alias pipe process 
382 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
384 Set up a mail alias called "issue_tracker" as (include the quote marks):
385 "``|/usr/bin/python /usr/local/bin/roundup-mailgw <tracker_home>``"
387 In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh so
388 sendmail will accept the pipe command. In that case, symlink
389 ``/etc/smrsh/roundup-mailgw`` to "``/usr/local/bin/roundup-mailgw``" and change
390 the command to::
392     |roundup-mailgw /opt/roundup/trackers/support
393  
394 To test the mail gateway on unix systems, try::
396     echo test |mail -s '[issue] test' support@YOUR_DOMAIN_HERE
398 As a regular job using a mailbox source
399 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
401 Set ``roundup-mailgw`` up to run every 10 minutes or so. For example::
403   0,10,20,30,40,50 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support mailbox <mail_spool_file>
405 Where the ``mail_spool_file`` argument is the location of the roundup submission
406 user's mail spool. On most systems, the spool for a user "issue_tracker"
407 will be "``/var/mail/issue_tracker``".
409 As a regular job using a POP source
410 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
412 To retrieve from a POP mailbox, use a *cron* entry similar to the mailbox one::
414   0,10,20,30,40,50 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support pop <pop_spec>
416 where pop_spec is "``username:password@server``" that specifies the roundup
417 submission user's POP account name, password and server.
419 On windows, you would set up the command using the windows scheduler.
422 UNIX Environment Steps
423 ----------------------
425 Each tracker ideally should have its own UNIX group, so create
426 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
427 you're using NIS).  To continue with my examples so far, I would
428 create the UNIX group 'support', although the name of the UNIX
429 group does not have to be the same as the tracker name.  To this
430 'support' group I then add all of the UNIX usernames who will be
431 working with this Roundup tracker.  In addition to 'real' users,
432 the Roundup email gateway will need to have permissions to this
433 area as well, so add the user your mail service runs as to the
434 group (typically "mail" or "daemon").  The UNIX group might then
435 look like::
437      support:*:1002:jblaine,samh,geezer,mail
439 If you intend to use the web interface (as most people do), you
440 should also add the username your web server runs as to the group.
441 My group now looks like this::
443      support:*:1002:jblaine,samh,geezer,mail,apache
445 The tracker "db" directory should be chmod'ed g+sw so that the group can
446 write to the database, and any new files created in the database will be owned
447 by the group.
449 An alternative to the above is to create a new user who has the sole
450 responsibility of running roundup. This user:
452 1. runs the CGI interface daemon
453 2. runs regular polls for email
454 3. runs regular checks (using cron) to ensure the daemon is up
455 4. optionally has no login password so that nobody but the "root" user
456    may actually login and play with the roundup setup.
459 Additional Language Codecs
460 --------------------------
462 If you intend to send messages to Roundup that use Chinese, Japanese or
463 Korean encodings the you'll need to obtain CJKCodecs from
464 http://cjkpython.berlios.de/
468 Maintenance
469 ===========
471 Read the separate `administration guide`_ for information about how to
472 perform common maintenance tasks with Roundup.
475 Upgrading
476 =========
478 Read the separate `upgrading document`_, which describes the steps needed to
479 upgrade existing tracker trackers for each version of Roundup that is
480 released.
483 Further Reading
484 ===============
486 If you intend to use Roundup with anything other than the defualt
487 templates, if you would like to hack on Roundup, or if you would
488 like implementation details, you should read `Customising Roundup`_.
491 Running Multiple Trackers
492 =========================
494 Things to think about before you jump off the deep end and install
495 multiple trackers, which involve additional URLs, user databases, email
496 addresses, databases to back up, etc.
498 1. Do you want a tracker per product you sell/support? You can just add
499    a new property to your issues called Product, and filter by that. See
500    the customisation example `adding a new field to the classic schema`_.
501 2. Do you want to track internal software development issues and customer
502    support issues separately? You can just set up an additional "issue"
503    class called "cust_issues" in the same tracker, mimicing the normal
504    "issue" class, but with different properties. See the customisation
505    example `tracking different types of issues`_.
508 Platform-Specific Notes
509 =======================
511 Windows command-line tools
512 --------------------------
514 To make the command-line tools accessible in Windows, you need to update
515 the "Path" environment variable in the Registry via a dialog box.
517 On Windows 2000 and later:
519 1) Press the "Start" button.
520 2) Choose "Settings"
521 3) Choose "Control Panel"
522 4) Choose "System"
523 5) Choose "Advanced"
524 6) Choose "Environmental Variables"
525 7) Add: "<dir>\Scripts" to the "Path" environmental variable.
527 Where <dir> in 7) is the root directory (e.g., ``C:\Python22\Scripts``)
528 of your Python installation.
530 I understand that in XP, 2) above is not needed as "Control
531 Panel" is directly accessible from "Start".
533 I do not believe this is possible to do in previous versions of Windows.
536 Windows Server
537 --------------
539 To have the Roundup web server start up when your machine boots up, set the
540 following up in Scheduled Tasks (note, the following is for a cygwin setup):
542 Run
543  ``c:\cygwin\bin\bash.exe -c "roundup-server TheProject=/opt/roundup/trackers/support"``
544 Start In
545  ``C:\cygwin\opt\roundup\bin``
546 Schedule
547  At System Startup
549 To have the Roundup mail gateway run periodically to poll a POP email address,
550 set the following up in Scheduled Tasks:
552 Run
553  ``c:\cygwin\bin\bash.exe -c "roundup-mailgw /opt/roundup/trackers/support pop roundup:roundup@mail-server"``
554 Start In
555  ``C:\cygwin\opt\roundup\bin``
556 Schedule
557  Every 10 minutes from 5:00AM for 24 hours every day
558  Stop the task if it runs for 8 minutes
561 Sendmail smrsh
562 --------------
564 If you use Sendmail's ``smrsh`` mechanism, you will need to tell
565 smrsh that roundup-mailgw is a valid/trusted mail handler
566 before it will work.
568 This is usually done via the following 2 steps:
570 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
571    which points to the full path of your actual ``roundup-mailgw``
572    script.
574 2. change your alias to ``"|roundup-mailgw <tracker_home>"``
577 Linux
578 -----
580 Make sure you read the instructions under `UNIX environment steps`_.
582 Python 2.1.1 as shipped with SuSE7.3 might be missing module
583 ``_weakref``.
586 Solaris
587 -------
589 You'll need to build Python.
591 Make sure you read the instructions under `UNIX environment steps`_.
594 -------------------------------------------------------------------------------
596 Back to `Table of Contents`_
598 Next: `User Guide`_
600 .. _`table of contents`: index.html
601 .. _`user guide`: user_guide.html
602 .. _`roundup specification`: spec.html
603 .. _`tracker configuration`: customizing.html#tracker-configuration
604 .. _`customisation documentation`: customizing.html
605 .. _`Adding a new field to the classic schema`:
606    customizing.html#adding-a-new-field-to-the-classic-schema
607 .. _`Tracking different types of issues`:
608    customizing.html#tracking-different-types-of-issues
609 .. _`customising roundup`: customizing.html
610 .. _`upgrading document`: upgrading.html
611 .. _`administration guide`: admin_guide.html
612 .. _sqlite: http://www.hwaci.com/sw/sqlite/
613 .. _metakit: http://www.equi4.com/metakit/
614 .. _Psycopg: http://initd.org/software/initd/psycopg
615 .. _MySQLdb: http://sourceforge.net/projects/mysql-python