1 ==================
2 Installing Roundup
3 ==================
5 :Version: $Revision: 1.43 $
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.1 - as these
37 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/).
48 Getting Roundup
49 ===============
51 Download the latest version from http://roundup.sf.net/.
53 Testing your Python
54 -------------------
56 Once you've unpacked roundup's source, run ``python ./run_tests`` in the
57 source directory and make sure there are no errors.
58 If there are errors, please let us know!
60 If the above fails, you may be using the wrong version of python. Try
61 ``python2 ./run_tests``. If that works, you will need to substitute
62 ``python2`` for ``python`` in all further commands you use in relation to
63 Roundup -- from installation and scripts.
66 Installation
67 ============
69 Set aside 15-30 minutes. Please make sure you're using a supported version of
70 Python -- see `testing your python`_. There's four steps to follow in your
71 installation:
73 1. `basic installation steps`_ that all installers must follow
74 2. then optionally `configure a web interface`_
75 3. and optionally `configure an email interface`_
76 4. `shared environment steps`_ to take if you're installing on a shared
77 UNIX machine and want to restrict local access to roundup
79 Most users will only need to follow the first step, since the environment will
80 be a trusted one.
83 Basic Installation Steps
84 ------------------------
86 1. To install the Roundup support code into your Python tree and
87 Roundup scripts into /usr/local/bin (substitute that path for whatever is
88 appropriate on your system). You need to have write permissions
89 for these locations, eg. being root on unix::
91 python setup.py install
93 If you would like to place the Roundup scripts in a directory other
94 than ``/usr/local/bin``, then specify the preferred location with
95 ``--install-script``. For example, to install them in
96 ``/opt/roundup/bin``::
98 python setup.py install --install-scripts=/opt/roundup/bin
100 You can also use the ``--prefix`` option to use a completely different
101 base directory, if you do not want to use administrator rights. If you
102 choose to do this, take note of the message at the end of installation
103 and modify the python path accordingly.
105 2. To create a Roundup tracker (necessary to do before you can
106 use the software in any real fashion):
108 a. (Optional) If you intend to keep your roundup trackers
109 under one top level directory which does not exist yet,
110 you should create that directory now. Example::
112 mkdir /opt/roundup/trackers
114 b. Either add the Roundup script location to your ``PATH``
115 environment variable or specify the full path to
116 the command in the next step.
118 c. Install a new tracker with the command ``roundup-admin install``.
119 You will be asked a series of questions. Descriptions of the provided
120 templates can be found in `choosing your template`_ below. Descriptions
121 of the available backends can be found in `choosing your backend`_
122 below. The questions will be something like (you may have more
123 templates or backends available)::
125 Enter tracker home: /opt/roundup/trackers/support
126 Templates: classic
127 Select template [classic]: classic
128 Back ends: anydbm, bsddb
129 Select backend [anydbm]: anydbm
131 The "support" part of the tracker name can be anything you want - it
132 is going to be used as the directory that the tracker information
133 will be stored in.
135 You will now be directed to edit the tracker configuration and
136 initial schema. At a minimum, you must set ``MAILHOST``,
137 ``TRACKER_WEB``, ``MAIL_DOMAIN`` and ``ADMIN_EMAIL``. Note that the
138 configuration file uses Python syntax, so almost every value must be
139 ``'quoted'`` using single or double quotes. If you get stuck, and get
140 configuration file errors, then see the `tracker configuration`_ section
141 of the `customisation documentation`_.
143 If you just want to get set up to test things quickly, you can even
144 just set the TRACKER_WEB variable to::
146 TRACKER_WEB = 'http://localhost:8080/support/'
148 The URL *must* end in a '/', or your web interface *will not work*.
149 See `Customising Roundup`_ for details on configuration and schema
150 changes. Note that you may change any of the configuration after
151 you've initialised the tracker - it's just better to have valid values
152 for this stuff now.
154 d. Initialise the tracker database with ``roundup-admin initialise``.
155 You will need to supply an admin password at this step. You will be
156 prompted::
158 Admin Password:
159 Confirm:
161 Once this is done, the tracker has been created.
163 3. At this point, your tracker is set up, but doesn't have a nice user
164 interface. To set that up, we need to `configure a web interface`_ and
165 optionally `configure an email interface`_. If you want to try your
166 new tracker out, assuming ``TRACKER_WEB`` is set to
167 ``'http://localhost:8080/support/'``, run::
169 roundup-server -p 8080 support=/opt/roundup/trackers/support
171 then direct your web browser at:
173 http://locahost:8080/support/
175 and you should see the tracker interface.
178 Choosing Your Template
179 ----------------------
181 Classic Template
182 ~~~~~~~~~~~~~~~~
184 The classic template is the one defined in the `Roundup Specification`_. It
185 holds issues which have priorities and statuses. Each issue may also have a
186 set of messages which are disseminated to the issue's list of nosy users.
188 Minimal Template
189 ~~~~~~~~~~~~~~~~
191 The minimal template has the minimum setup required for a tracker
192 installation. That is, it has the configuration files, defines a user database
193 and the basic HTML interface to that. It's a completely clean slate for you to
194 create your tracker on.
197 Choosing Your Backend
198 ---------------------
200 The actual storage of Roundup tracker information is handled by backends.
201 There's several to choose from, each with benefits and limitations:
203 **anydbm**
204 This backend is guaranteed to work on any system that Python runs on. It
205 will generally choose the best dbm backend that is available on your system
206 (from the list dbhash, gdbm, dbm, dumbdbm). It is the least scaleable of all
207 backends, but performs well enough for a smallish tracker (a couple of
208 thousand issues, under fifty users, ...).
209 **bsddb**
210 This effectively the same as anydbm, but uses the bsddb backend. This allows
211 it to gain some performance and scaling benefits.
212 **bsddb3**
213 Again, this effectively the same as anydbm, but uses the bsddb3 backend.
214 This allows it to gain some performance and scaling benefits.
215 **sqlite**
216 This uses the SQLite_ embedded RDBMS to provide a fast, scaleable backend.
217 There are no limitations, and it's much faster and more scaleable than the
218 dbm backends.
219 **mysql**
220 Backend for popular RDBMS MySQL. This backend uses MySQL's Berkeley DB
221 (transaction safe) table format, so with small amount of data it may be a
222 bit slower than \*dbm backends (due to mysql layer's overhead). However with
223 lots of data mysql may perform better (due to query optimisation). No actual
224 serious benchmarks were made though. For more info on installation of this
225 backend see doc/mysql.txt.
226 **metakit**
227 This backend is implemented over the metakit_ storage system, using Mk4Py as
228 the interface. It scales much better than the dbm backends.
230 Note: you may set your tracker up with the anydbm backend (which is guaranteed
231 to be available) and switch to one of the other backends at any time using the
232 instructions in the `maintenance documentation`_.
235 Configure a Web Interface
236 -------------------------
238 There are three web interfaces to choose from:
240 1. `web server cgi-bin`_
241 2. `stand-alone web server`_
242 3. `Zope product - ZRoundup`_
244 You may need to give the web server user permission to access the tracker home
245 - see the `shared environment steps`_ for information.
248 Web Server cgi-bin
249 ~~~~~~~~~~~~~~~~~~
251 A benefit of using the cgi-bin approach is that it's the easiest way to
252 restrict access to your tracker to only use HTTPS. Access will be slower
253 than through the `stand-alone web server`_ though.
255 If you're using IIS on a Windows platform, you'll need to run this command
256 for the cgi to work (it turns on the PATH_INFO cgi variable)::
258 adsutil.vbs set w3svc/AllowPathInfoForScriptMappings TRUE
260 The ``adsutil.vbs`` file can be found in either ``c:\inetpub\adminscripts``
261 or ``c:\winnt\system32\inetsrv\adminsamples\`` or
262 ``c:\winnt\system32\inetsrv\adminscripts\`` depending on your installation.
264 Copy the ``cgi-bin/roundup.cgi`` file to your web server's ``cgi-bin``
265 directory. You will need to configure it to tell it where your tracker home
266 is. You can do this either:
268 through an environment variable
269 set the variable TRACKER_HOMES to be a colon (":") separated list of
270 name=home pairs (if you're using apache, the SetEnv directive can do this)
271 directly in the ``roundup.cgi`` file itself
272 add your instance to the TRACKER_HOMES variable as ``'name': 'home'``
274 The "name" part of the configuration will appear in the URL and identifies the
275 tracker (so you may have more than one tracker per cgi-bin script). Make sure
276 there are no spaces or other illegal characters in it (to be safe, stick to
277 letters and numbers). The "name" forms part of the URL that appears in the
278 tracker config TRACKER_WEB variable, so make sure they match. The "home"
279 part of the configuration is the tracker home directory.
281 Stand-alone Web Server
282 ~~~~~~~~~~~~~~~~~~~~~~
284 This approach will give you the fastest of the three web interfaces. You may
285 investigate using ProxyPass or similar configuration in apache to have your
286 tracker accessed through the same URL as other systems.
288 The stand-alone web server is started with the command ``roundup-server``. It
289 has several options - display them with ``roundup-server -h``.
291 The tracker home configuration is similar to the cgi-bin - you may either edit
292 the script to change the TRACKER_HOMES variable or you may supply the
293 name=home values on the command-line after all the other options.
295 To make the server run in the background, use the "-d" option, specifying the
296 name of a file to write the server process id (pid) to.
299 Zope Product - ZRoundup
300 ~~~~~~~~~~~~~~~~~~~~~~~
302 ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
303 your Products directory either in INSTANCE_HOME/Products or the Zope
304 code tree lib/python/Products.
306 When you next (re)start up Zope, you will be able to add a ZRoundup object
307 that interfaces to your new tracker.
310 Configure an Email Interface
311 ----------------------------
313 If you don't want to use the email component of Roundup, then remove the
314 "``nosyreaction.py``" module from your tracker "``detectors``" directory.
316 There are three supported ways to get emailed issues into the
317 Roundup tracker. You should pick ONE of the following, all
318 of which will continue my example setup from above:
320 As a mail alias pipe process
321 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
323 Set up a mail alias called "issue_tracker" as (include the quote marks):
324 "``|/usr/bin/python /usr/local/bin/roundup-mailgw <tracker_home>``"
326 In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh so
327 sendmail will accept the pipe command. In that case, symlink
328 ``/etc/smrsh/roundup-mailgw`` to "``/usr/local/bin/roundup-mailgw``" and change
329 the command to::
331 |roundup-mailgw /opt/roundup/trackers/support
333 To test the mail gateway on unix systems, try::
335 echo test |mail -s '[issue] test' support@YOUR_DOMAIN_HERE
337 As a regular job using a mailbox source
338 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
340 Set ``roundup-mailgw`` up to run every 10 minutes or so. For example::
342 10 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support mailbox <mail_spool_file>
344 Where the ``mail_spool_file`` argument is the location of the roundup submission
345 user's mail spool. On most systems, the spool for a user "issue_tracker"
346 will be "``/var/mail/issue_tracker``".
348 As a regular job using a POP source
349 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
351 To retrieve from a POP mailbox, use a *cron* entry to the mailbox one::
353 10 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support pop <pop_spec>
355 where pop_spec is "``username:password@server``" that specifies the roundup
356 submission user's POP account name, password and server.
358 On windows, you would set up the command using the windows scheduler.
361 Shared Environment Steps
362 ------------------------
364 Each tracker ideally should have its own UNIX group, so create
365 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
366 you're using NIS). To continue with my examples so far, I would
367 create the UNIX group 'support', although the name of the UNIX
368 group does not have to be the same as the tracker name. To this
369 'support' group I then add all of the UNIX usernames who will be
370 working with this Roundup tracker. In addition to 'real' users,
371 the Roundup email gateway will need to have permissions to this
372 area as well, so add the user your mail service runs as to the
373 group. The UNIX group might then look like::
375 support:*:1002:jblaine,samh,geezer,mail
377 If you intend to use the web interface (as most people do), you
378 should also add the username your web server runs as to the group.
379 My group now looks like this::
381 support:*:1002:jblaine,samh,geezer,mail,apache
383 The tracker "db" directory should be chmod'ed g+sw so that the group can
384 write to the database, and any new files created in the database will be owned
385 by the group.
387 An alternative to the above is to create a new user who has the sole
388 responsibility of running roundup. This user:
390 1. runs the CGI interface daemon
391 2. runs regular polls for email
392 3. runs regular checks (using cron) to ensure the daemon is up
393 4. optionally has no login password so that nobody but the "root" user
394 may actually login and play with the roundup setup.
397 Maintenance
398 ===========
400 Read the separate `maintenance documentation`_ for information about how to
401 perform common maintenance tasks with Roundup.
404 Upgrading
405 =========
407 Read the separate `upgrading document`_, which describes the steps needed to
408 upgrade existing tracker trackers for each version of Roundup that is
409 released.
412 Further Reading
413 ===============
415 If you intend to use Roundup with anything other than the defualt
416 templates, if you would like to hack on Roundup, or if you would
417 like implementation details, you should read `Customising Roundup`_.
420 Platform-Specific Notes
421 =======================
423 Sendmail smrsh
424 --------------
426 If you use Sendmail's ``smrsh`` mechanism, you will need to tell
427 smrsh that roundup-mailgw is a valid/trusted mail handler
428 before it will work.
430 This is usually done via the following 2 steps:
432 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
433 which points to the full path of your actual ``roundup-mailgw``
434 script.
436 2. change your alias to ``"|roundup-mailgw <tracker_home>"``
439 Linux
440 -----
442 Python 2.1.1 as shipped with SuSE7.3 might be missing module
443 ``_weakref``.
445 -------------------------------------------------------------------------------
447 Back to `Table of Contents`_
449 Next: `User Guide`_
451 .. _`table of contents`: index.html
452 .. _`user guide`: user_guide.html
453 .. _`roundup specification`: spec.html
454 .. _`tracker configuration`: customizing.html#tracker-configuration
455 .. _`customisation documentation`: customizing.html
456 .. _`customising roundup`: customizing.html
457 .. _`upgrading document`: upgrading.html
458 .. _`maintenance documentation`: maintenance.html
459 .. _sqlite: http://www.hwaci.com/sw/sqlite/
460 .. _metakit: http://www.equi4.com/metakit/