1 ==================
2 Installing Roundup
3 ==================
5 :Version: $Revision: 1.40 $
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 **mysql**
216 Backend for popular RDBMS MySQL. This backend uses MySQL's Berkeley DB
217 (transaction safe) table format, so with small amount of data it may be a
218 bit slower than *dbm backends (due to mysql layer's overhead). However with
219 lots of data mysql may perform better (due to query optimisation). No actual
220 serious benchmarks were made though. For more info on installation of this
221 backend see doc/mysql.txt.
222 **metakit**
223 This backend is implemented over the metakit_ storage system, using Mk4Py as
224 the interface. It scales much better than the dbm backends.
226 Note: you may set your tracker up with the anydbm backend (which is guaranteed
227 to be available) and switch to one of the other backends at any time using the
228 instructions in the `maintenance documentation`_.
231 Configure a Web Interface
232 -------------------------
234 There are three web interfaces to choose from:
236 1. `web server cgi-bin`_
237 2. `stand-alone web server`_
238 3. `Zope product - ZRoundup`_
240 You may need to give the web server user permission to access the tracker home
241 - see the `shared environment steps`_ for information.
244 Web Server cgi-bin
245 ~~~~~~~~~~~~~~~~~~
247 A benefit of using the cgi-bin approach is that it's the easiest way to
248 restrict access to your tracker to only use HTTPS. Access will be slower
249 than through the `stand-alone web server`_ though.
251 Copy the ``cgi-bin/roundup.cgi`` file to your web server's ``cgi-bin``
252 directory. You will need to configure it to tell it where your tracker home
253 is. You can do this either:
255 through an environment variable
256 set the variable TRACKER_HOMES to be a colon (":") separated list of
257 name=home pairs (if you're using apache, the SetEnv directive can do this)
258 directly in the ``roundup.cgi`` file itself
259 add your instance to the TRACKER_HOMES variable as ``'name': 'home'``
261 The "name" part of the configuration will appear in the URL and identifies the
262 tracker (so you may have more than one tracker per cgi-bin script). Make sure
263 there are no spaces or other illegal characters in it (to be safe, stick to
264 letters and numbers). The "name" forms part of the URL that appears in the
265 tracker config TRACKER_WEB variable, so make sure they match. The "home"
266 part of the configuration is the tracker home directory.
268 Stand-alone Web Server
269 ~~~~~~~~~~~~~~~~~~~~~~
271 This approach will give you the fastest of the three web interfaces. You may
272 investigate using ProxyPass or similar configuration in apache to have your
273 tracker accessed through the same URL as other systems.
275 The stand-alone web server is started with the command ``roundup-server``. It
276 has several options - display them with ``roundup-server -h``.
278 The tracker home configuration is similar to the cgi-bin - you may either edit
279 the script to change the TRACKER_HOMES variable or you may supply the
280 name=home values on the command-line after all the other options.
282 To make the server run in the background, use the "-d" option, specifying the
283 name of a file to write the server process id (pid) to.
286 Zope Product - ZRoundup
287 ~~~~~~~~~~~~~~~~~~~~~~~
289 ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
290 your Products directory either in INSTANCE_HOME/Products or the Zope
291 code tree lib/python/Products.
293 When you next (re)start up Zope, you will be able to add a ZRoundup object
294 that interfaces to your new tracker.
297 Configure an Email Interface
298 ----------------------------
300 If you don't want to use the email component of Roundup, then remove the
301 "``nosyreaction.py``" module from your tracker "``detectors``" directory.
303 There are three supported ways to get emailed issues into the
304 Roundup tracker. You should pick ONE of the following, all
305 of which will continue my example setup from above:
307 As a mail alias pipe process
308 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
310 Set up a mail alias called "issue_tracker" as (include the quote marks):
311 "``|/usr/bin/python /usr/local/bin/roundup-mailgw <tracker_home>``"
313 In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh so
314 sendmail will accept the pipe command. In that case, symlink
315 ``/etc/smrsh/roundup-mailgw`` to "``/usr/local/bin/roundup-mailgw``" and change
316 the command to::
318 |roundup-mailgw /opt/roundup/trackers/support
320 To test the mail gateway on unix systems, try::
322 echo test |mail -s '[issue] test' support@YOUR_DOMAIN_HERE
324 As a regular job using a mailbox source
325 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
327 Set ``roundup-mailgw`` up to run every 10 minutes or so. For example::
329 10 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support mailbox <mail_spool_file>
331 Where the ``mail_spool_file`` argument is the location of the roundup submission
332 user's mail spool. On most systems, the spool for a user "issue_tracker"
333 will be "``/var/mail/issue_tracker``".
335 As a regular job using a POP source
336 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
338 To retrieve from a POP mailbox, use a *cron* entry to the mailbox one::
340 10 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support pop <pop_spec>
342 where pop_spec is "``username:password@server``" that specifies the roundup
343 submission user's POP account name, password and server.
345 On windows, you would set up the command using the windows scheduler.
348 Shared Environment Steps
349 ------------------------
351 Each tracker ideally should have its own UNIX group, so create
352 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
353 you're using NIS). To continue with my examples so far, I would
354 create the UNIX group 'support', although the name of the UNIX
355 group does not have to be the same as the tracker name. To this
356 'support' group I then add all of the UNIX usernames who will be
357 working with this Roundup tracker. In addition to 'real' users,
358 the Roundup email gateway will need to have permissions to this
359 area as well, so add the user your mail service runs as to the
360 group. The UNIX group might then look like::
362 support:*:1002:jblaine,samh,geezer,mail
364 If you intend to use the web interface (as most people do), you
365 should also add the username your web server runs as to the group.
366 My group now looks like this::
368 support:*:1002:jblaine,samh,geezer,mail,apache
370 The tracker "db" directory should be chmod'ed g+sw so that the group can
371 write to the database, and any new files created in the database will be owned
372 by the group.
374 An alternative to the above is to create a new user who has the sole
375 responsibility of running roundup. This user:
377 1. runs the CGI interface daemon
378 2. runs regular polls for email
379 3. runs regular checks (using cron) to ensure the daemon is up
380 4. optionally has no login password so that nobody but the "root" user
381 may actually login and play with the roundup setup.
384 Maintenance
385 ===========
387 Read the separate `maintenance documentation`_ for information about how to
388 perform common maintenance tasks with Roundup.
391 Upgrading
392 =========
394 Read the separate `upgrading document`_, which describes the steps needed to
395 upgrade existing tracker trackers for each version of Roundup that is
396 released.
399 Further Reading
400 ===============
402 If you intend to use Roundup with anything other than the defualt
403 templates, if you would like to hack on Roundup, or if you would
404 like implementation details, you should read `Customising Roundup`_.
407 Platform-Specific Notes
408 =======================
410 Sendmail smrsh
411 --------------
413 If you use Sendmail's ``smrsh`` mechanism, you will need to tell
414 smrsh that roundup-mailgw is a valid/trusted mail handler
415 before it will work.
417 This is usually done via the following 2 steps:
419 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
420 which points to the full path of your actual ``roundup-mailgw``
421 script.
423 2. change your alias to ``"|roundup-mailgw <tracker_home>"``
426 Linux
427 -----
429 Python 2.1.1 as shipped with SuSE7.3 might be missing module
430 ``_weakref``.
432 -------------------------------------------------------------------------------
434 Back to `Table of Contents`_
436 Next: `User Guide`_
438 .. _`table of contents`: index.html
439 .. _`user guide`: user_guide.html
440 .. _`roundup specification`: spec.html
441 .. _`tracker configuration`: customizing.html#tracker-configuration
442 .. _`customisation documentation`: customizing.html
443 .. _`customising roundup`: customizing.html
444 .. _`upgrading document`: upgrading.html
445 .. _`maintenance documentation`: maintenance.html
446 .. _sqlite: http://www.hwaci.com/sw/sqlite/
447 .. _metakit: http://www.equi4.com/metakit/