1 ==================
2 Installing Roundup
3 ==================
5 :Version: $Revision: 1.37 $
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 You will now be directed to edit the tracker configuration and
132 initial schema. At a minimum, you must set ``MAILHOST``,
133 ``TRACKER_WEB``, ``MAIL_DOMAIN`` and ``ADMIN_EMAIL``. Note that the
134 configuration file uses Python syntax, so almost every value must be
135 ``'quoted'`` using single or double quotes. If you get stuck, and get
136 configuration file errors, then see the `tracker configuration`_ section
137 of the `customisation documentation`_.
139 If you just want to get set up to test things quickly, you can even
140 just set the TRACKER_WEB variable to::
142 TRACKER_WEB = 'http://localhost:8080/support/'
144 The URL *must* end in a '/', or your web interface *will not work*.
145 See `Customising Roundup`_ for details on configuration and schema
146 changes. Note that you may change any of the configuration after
147 you've initialised the tracker - it's just better to have valid values
148 for this stuff now.
150 d. Initialise the tracker database with ``roundup-admin initialise``.
151 You will need to supply an admin password at this step. You will be
152 prompted::
154 Admin Password:
155 Confirm:
157 Once this is done, the tracker has been created.
159 3. At this point, your tracker is set up, but doesn't have a nice user
160 interface. To set that up, we need to `configure a web interface`_ and
161 optionally `configure an email interface`_. If you want to try your
162 new tracker out, assuming ``TRACKER_WEB`` is set to
163 ``'http://localhost:8080/support/'``, run::
165 roundup-server -p 8080 support=/opt/roundup/trackers/support
167 then direct your web browser at:
169 http://locahost:8080/support/
171 and you should see the tracker interface.
174 Choosing Your Template
175 ----------------------
177 Classic Template
178 ~~~~~~~~~~~~~~~~
180 The classic template is the one defined in the `Roundup Specification`_. It
181 holds issues which have priorities and statuses. Each issue may also have a
182 set of messages which are disseminated to the issue's list of nosy users.
184 Minimal Template
185 ~~~~~~~~~~~~~~~~
187 The minimal template has the minimum setup required for a tracker
188 installation. That is, it has the configuration files, defines a user database
189 and the basic HTML interface to that. It's a completely clean slate for you to
190 create your tracker on.
193 Choosing Your Backend
194 ---------------------
196 The actual storage of Roundup tracker information is handled by backends.
197 There's several to choose from, each with benefits and limitations:
199 **anydbm**
200 This backend is guaranteed to work on any system that Python runs on. It
201 will generally choose the best dbm backend that is available on your system
202 (from the list dbhash, gdbm, dbm, dumbdbm). It is the least scaleable of all
203 backends, but performs well enough for a smallish tracker (a couple of
204 thousand issues, under fifty users, ...).
205 **bsddb**
206 This effectively the same as anydbm, but uses the bsddb backend. This allows
207 it to gain some performance and scaling benefits.
208 **bsddb3**
209 Again, this effectively the same as anydbm, but uses the bsddb3 backend.
210 This allows it to gain some performance and scaling benefits.
211 **sqlite**
212 This uses the SQLite_ embedded RDBMS to provide a fast, scaleable backend.
213 There are no limitations, and it's much faster and more scaleable than the
214 dbm backends.
215 **metakit**
216 This backend is implemented over the metakit_ storage system, using Mk4Py as
217 the interface. It scales much better than the dbm backends.
218 **gadfly**
219 This is a proof-of-concept relational database backend, not really intended
220 for actual production use, although it can be. It uses the Gadfly RDBMS
221 to store data. It is unable to perform string searches due to gadfly not
222 having a LIKE operation. It should scale well, assuming a client/server
223 setup is used. It's much slower than even the dbm backends.
225 Note: you may set your tracker up with the anydbm backend (which is guaranteed
226 to be available) and switch to one of the other backends at any time using the
227 instructions in the `maintenance documentation`_.
230 Configure a Web Interface
231 -------------------------
233 There are three web interfaces to choose from:
235 1. `web server cgi-bin`_
236 2. `stand-alone web server`_
237 3. `Zope product - ZRoundup`_
239 You may need to give the web server user permission to access the tracker home
240 - see the `shared environment steps`_ for information.
243 Web Server cgi-bin
244 ~~~~~~~~~~~~~~~~~~
246 A benefit of using the cgi-bin approach is that it's the easiest way to
247 restrict access to your tracker to only use HTTPS. Access will be slower
248 than through the `stand-alone web server`_ though.
250 Copy the ``cgi-bin/roundup.cgi`` file to your web server's ``cgi-bin``
251 directory. You will need to configure it to tell it where your tracker home
252 is. You can do this either:
254 through an environment variable
255 set the variable TRACKER_HOMES to be a colon (":") separated list of
256 name=home pairs (if you're using apache, the SetEnv directive can do this)
257 directly in the ``roundup.cgi`` file itself
258 add your instance to the TRACKER_HOMES variable as ``'name': 'home'``
260 The "name" part of the configuration will appear in the URL and identifies the
261 tracker (so you may have more than one tracker per cgi-bin script). Make sure
262 there are no spaces or other illegal characters in it (to be safe, stick to
263 letters and numbers). The "name" forms part of the URL that appears in the
264 tracker config TRACKER_WEB variable, so make sure they match. The "home"
265 part of the configuration is the tracker home directory.
267 Stand-alone Web Server
268 ~~~~~~~~~~~~~~~~~~~~~~
270 This approach will give you the fastest of the three web interfaces. You may
271 investigate using ProxyPass or similar configuration in apache to have your
272 tracker accessed through the same URL as other systems.
274 The stand-alone web server is started with the command ``roundup-server``. It
275 has several options - display them with ``roundup-server -h``.
277 The tracker home configuration is similar to the cgi-bin - you may either edit
278 the script to change the TRACKER_HOMES variable or you may supply the
279 name=home values on the command-line after all the other options.
281 To make the server run in the background, use the "-d" option, specifying the
282 name of a file to write the server process id (pid) to.
285 Zope Product - ZRoundup
286 ~~~~~~~~~~~~~~~~~~~~~~~
288 ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
289 your Products directory either in INSTANCE_HOME/Products or the Zope
290 code tree lib/python/Products.
292 When you next (re)start up Zope, you will be able to add a ZRoundup object
293 that interfaces to your new tracker.
296 Configure an Email Interface
297 ----------------------------
299 If you don't want to use the email component of Roundup, then remove the
300 "``nosyreator.py``" module from your tracker "``detectors``" directory.
302 There are three supported ways to get emailed issues into the
303 Roundup tracker. You should pick ONE of the following, all
304 of which will continue my example setup from above:
306 As a mail alias pipe process
307 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
309 Set up a mail alias called "issue_tracker" as (include the quote marks):
310 "``|/usr/bin/python /usr/local/bin/roundup-mailgw <tracker_home>``"
312 In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh so
313 sendmail will accept the pipe command. In that case, symlink
314 ``/etc/smrsh/roundup-mailgw`` to "``/usr/local/bin/roundup-mailgw``" and change
315 the command to::
317 |roundup-mailgw /opt/roundup/trackers/support
319 To test the mail gateway on unix systems, try::
321 echo test |mail -s '[issue] test' support@YOUR_DOMAIN_HERE
323 As a regular job using a mailbox source
324 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
326 Set ``roundup-mailgw`` up to run every 10 minutes or so. For example::
328 10 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support mailbox <mail_spool_file>
330 Where the ``mail_spool_file`` argument is the location of the roundup submission
331 user's mail spool. On most systems, the spool for a user "issue_tracker"
332 will be "``/var/mail/issue_tracker``".
334 As a regular job using a POP source
335 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
337 To retrieve from a POP mailbox, use a *cron* entry to the mailbox one::
339 10 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support pop <pop_spec>
341 where pop_spec is "``username:password@server``" that specifies the roundup
342 submission user's POP account name, password and server.
344 On windows, you would set up the command using the windows scheduler.
347 Shared Environment Steps
348 ------------------------
350 Each tracker ideally should have its own UNIX group, so create
351 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
352 you're using NIS). To continue with my examples so far, I would
353 create the UNIX group 'support', although the name of the UNIX
354 group does not have to be the same as the tracker name. To this
355 'support' group I then add all of the UNIX usernames who will be
356 working with this Roundup tracker. In addition to 'real' users,
357 the Roundup email gateway will need to have permissions to this
358 area as well, so add the user your mail service runs as to the
359 group. The UNIX group might then look like::
361 support:*:1002:jblaine,samh,geezer,mail
363 If you intend to use the web interface (as most people do), you
364 should also add the username your web server runs as to the group.
365 My group now looks like this::
367 support:*:1002:jblaine,samh,geezer,mail,apache
369 The tracker "db" directory should be chmod'ed g+sw so that the group can
370 write to the database, and any new files created in the database will be owned
371 by the group.
373 An alternative to the above is to create a new user who has the sole
374 responsibility of running roundup. This user:
376 1. runs the CGI interface daemon
377 2. runs regular polls for email
378 3. runs regular checks (using cron) to ensure the daemon is up
379 4. optionally has no login password so that nobody but the "root" user
380 may actually login and play with the roundup setup.
383 Maintenance
384 ===========
386 Read the separate `maintenance documentation`_ for information about how to
387 perform common maintenance tasks with Roundup.
390 Upgrading
391 =========
393 Read the separate `upgrading document`_, which describes the steps needed to
394 upgrade existing tracker trackers for each version of Roundup that is
395 released.
398 Further Reading
399 ===============
401 If you intend to use Roundup with anything other than the defualt
402 templates, if you would like to hack on Roundup, or if you would
403 like implementation details, you should read `Customising Roundup`_.
406 Platform-Specific Notes
407 =======================
409 Sendmail smrsh
410 --------------
412 If you use Sendmail's ``smrsh`` mechanism, you will need to tell
413 smrsh that roundup-mailgw is a valid/trusted mail handler
414 before it will work.
416 This is usually done via the following 2 steps:
418 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
419 which points to the full path of your actual ``roundup-mailgw``
420 script.
422 2. change your alias to ``"|roundup-mailgw <tracker_home>"``
425 Linux
426 -----
428 Python 2.1.1 as shipped with SuSE7.3 might be missing module
429 ``_weakref``.
431 -------------------------------------------------------------------------------
433 Back to `Table of Contents`_
435 Next: `User Guide`_
437 .. _`table of contents`: index.html
438 .. _`user guide`: user_guide.html
439 .. _`roundup specification`: spec.html
440 .. _`tracker configuration`: customizing.html#tracker-configuration
441 .. _`customisation documentation`: customizing.html
442 .. _`customising roundup`: customizing.html
443 .. _`upgrading document`: upgrading.html
444 .. _`maintenance documentation`: maintenance.html
445 .. _sqlite: http://www.hwaci.com/sw/sqlite/
446 .. _metakit: http://www.equi4.com/metakit/