4d8e114a408d76610332df62cf6dfae918c76e56
1 ==================
2 Installing Roundup
3 ==================
5 :Version: $Revision: 1.32 $
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/.
43 Getting Roundup
44 ===============
46 Download the latest version from http://roundup.sf.net/.
48 Testing your Python
49 -------------------
51 Once you've unpacked roundup's source, run ``python ./run_tests`` in the
52 source directory and make sure there are no errors.
53 If there are errors, please let us know!
55 If the above fails, you may be using the wrong version of python. Try
56 ``python2 ./run_tests``. If that works, you will need to substitute
57 ``python2`` for ``python`` in all further commands you use in relation to
58 Roundup -- from installation and scripts.
61 Installation
62 ============
64 Set aside 15-30 minutes. Please make sure you're using a supported version of
65 Python -- see `testing your python`_. There's four steps to follow in your
66 installation:
68 1. `basic installation steps`_ that all installers must follow
69 2. then optionally `configure a web interface`_
70 3. and optionally `configure an email interface`_
71 4. `shared environment steps`_ to take if you're installing on a shared
72 UNIX machine and want to restrict local access to roundup
74 Most users will only need to follow the first step, since the environment will
75 be a trusted one.
78 Basic Installation Steps
79 ------------------------
81 1. To install the Roundup support code into your Python tree and
82 Roundup scripts into /usr/local/bin. You need to have write permissions
83 for these locations, eg. being root on unix::
85 python setup.py install
87 If you would like to place the Roundup scripts in a directory other
88 than ``/usr/local/bin``, then specify the preferred location with
89 ``--install-script``. For example, to install them in
90 ``/opt/roundup/bin``::
92 python setup.py install --install-scripts=/opt/roundup/bin
94 You can also use the ``--prefix`` option to use a completely different
95 base directory, if you do not want to use administrator rights. If you
96 choose to do this, take note of the message at the end of installation
97 and modify the python path accordingly.
99 2. To create a Roundup tracker (necessary to do before you can
100 use the software in any real fashion):
102 a. (Optional) If you intend to keep your roundup trackers
103 under one top level directory which does not exist yet,
104 you should create that directory now. Example::
106 mkdir /opt/roundup/trackers
108 b. Either add the Roundup script location to your ``PATH``
109 environment variable or specify the full path to
110 the command in the next step.
112 c. Install a new tracker with the command ``roundup-admin install``.
113 You will be asked a series of questions. Descriptions of the provided
114 templates can be found in `choosing your template`_ below. Descriptions
115 of the available backends can be found in `choosing your backend`_
116 below. The questions will be something like (you may have more
117 templates or backends available)::
119 Enter tracker home: /opt/roundup/trackers/support
120 Templates: classic
121 Select template [classic]: classic
122 Back ends: anydbm, bsddb
123 Select backend [anydbm]: anydbm
125 You will now be directed to edit the tracker configuration and
126 initial schema. At a minimum, you must set ``MAILHOST``,
127 ``TRACKER_WEB``, ``MAIL_DOMAIN`` and ``ADMIN_EMAIL``. Note that the
128 configuration file uses Python syntax, so almost every value must be
129 ``'quoted'`` using single or double quotes. If you get stuck, and get
130 configuration file errors, then see the `tracker configuration`_ section
131 of the `customisation documentation`_.
133 If you just want to get set up to test things quickly, you can even
134 just set the TRACKER_WEB variable to::
136 TRACKER_WEB = 'http://localhost:8080/support/'
138 See `Customising Roundup`_ for details on configuration
139 and schema changes. Note that you may change any of the configuration
140 after you've initialised the tracker - it's just better to have valid
141 values for this stuff now.
143 d. Initialise the tracker database with ``roundup-admin initialise``.
144 You will need to supply an admin password at this step. You will be
145 prompted::
147 Admin Password:
148 Confirm:
150 Once this is done, the tracker has been created.
152 3. At this point, your tracker is set up, but doesn't have a nice user
153 interface. To set that up, we need to `configure a web interface`_ and
154 optionally `configure an email interface`_. To quickly test the web
155 interface, assuming ``TRACKER_WEB`` is set to
156 ``'http://localhost:8080/support/'``::
158 roundup-server -p 8080 support=/opt/roundup/trackers/support
160 then direct your web browser at:
162 http://locahost:8080/support/
164 and you should see the tracker interface.
167 Choosing Your Template
168 ----------------------
170 Classic Template
171 ~~~~~~~~~~~~~~~~
173 The classic template is the one defined in the `Roundup Specification`_. It
174 holds issues which have priorities and statuses. Each issue may also have a
175 set of messages which are disseminated to the issue's list of nosy users.
177 Minimal Template
178 ~~~~~~~~~~~~~~~~
180 The minimal template has the minimum setup required for a tracker
181 installation. That is, it has the configuration files, defines a user database
182 and the basic HTML interface to that. It's a completely clean slate for you to
183 create your tracker on.
186 Choosing Your Backend
187 ---------------------
189 The actual storage of Roundup tracker information is handled by backends.
190 There's several to choose from, each with benefits and limitations:
192 **anydbm**
193 This backend is guaranteed to work on any system that Python runs on. It
194 will generally choose the best dbm backend that is available on your system
195 (from the list dbhash, gdbm, dbm, dumbdbm). It is the least scaleable of all
196 backends, but performs well enough for a smallish tracker (a couple of
197 thousand issues, under fifty users, ...).
198 **bsddb**
199 This effectively the same as anydbm, but uses the bsddb backend. This allows
200 it to gain some performance and scaling benefits.
201 **bsddb3**
202 Again, this effectively the same as anydbm, but uses the bsddb3 backend.
203 This allows it to gain some performance and scaling benefits.
204 **sqlite**
205 This uses the SQLite_ embedded RDBMS to provide a fast, scaleable backend.
206 There are no limitations, and it's much faster and more scaleable than the
207 dbm backends.
208 **metakit**
209 This backend is implemented over the metakit_ storage system, using Mk4Py as
210 the interface. It scales much better than the dbm backends.
211 **gadfly**
212 This is a proof-of-concept relational database backend, not really intended
213 for actual production use, although it can be. It uses the Gadfly RDBMS
214 to store data. It is unable to perform string searches due to gadfly not
215 having a LIKE operation. It should scale well, assuming a client/server
216 setup is used. It's much slower than even the dbm backends.
218 Note: you may set your tracker up with the anydbm backend (which is guaranteed
219 to be available) and switch to one of the other backends at any time using the
220 instructions in the `maintenance documentation`_.
223 Configure a Web Interface
224 -------------------------
226 There are three web interfaces to choose from:
228 1. `web server cgi-bin`_
229 2. `stand-alone web server`_
230 3. `Zope product - ZRoundup`_
232 You may need to give the web server user permission to access the tracker home
233 - see the `shared environment steps`_ for information.
236 Web Server cgi-bin
237 ~~~~~~~~~~~~~~~~~~
239 A benefit of using the cgi-bin approach is that it's the easiest way to
240 restrict access to your tracker to only use HTTPS. Access will be slower
241 than through the `stand-alone web server`_ though.
243 Copy the ``cgi-bin/roundup.cgi`` file to your web server's ``cgi-bin``
244 directory. You will need to configure it to tell it where your tracker home
245 is. You can do this either:
247 through an environment variable
248 set the variable TRACKER_HOMES to be a colon (":") separated list of
249 name=home pairs (if you're using apache, the SetEnv directive can do this)
250 directly in the ``roundup.cgi`` file itself
251 add your instance to the TRACKER_HOMES variable as ``'name': 'home'``
253 The "name" part of the configuration will appear in the URL and identifies the
254 tracker (so you may have more than one tracker per cgi-bin script). Make sure
255 there are no spaces or other illegal characters in it (to be safe, stick to
256 letters and numbers). The "name" forms part of the URL that appears in the
257 tracker config TRACKER_WEB variable, so make sure they match. The "home"
258 part of the configuration is the tracker home directory.
260 Stand-alone Web Server
261 ~~~~~~~~~~~~~~~~~~~~~~
263 This approach will give you the fastest of the three web interfaces. You may
264 investigate using ProxyPass or similar configuration in apache to have your
265 tracker accessed through the same URL as other systems.
267 The stand-alone web server is started with the command ``roundup-server``. It
268 has several options - display them with ``roundup-server -h``.
270 The tracker home configuration is similar to the cgi-bin - you may either edit
271 the script to change the TRACKER_HOMES variable or you may supply the
272 name=home values on the command-line after all the other options.
274 To make the server run in the background, use the "-d" option, specifying the
275 name of a file to write the server process id (pid) to.
278 Zope Product - ZRoundup
279 ~~~~~~~~~~~~~~~~~~~~~~~
281 ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
282 your Products directory either in INSTANCE_HOME/Products or the Zope
283 code tree lib/python/Products.
285 When you next (re)start up Zope, you will be able to add a ZRoundup object
286 that interfaces to your new tracker.
289 Configure an Email Interface
290 ----------------------------
292 If you don't want to use the email component of Roundup, then remove the
293 "``nosyreator.py``" module from your tracker "``detectors``" directory.
295 There are three supported ways to get emailed issues into the
296 Roundup tracker. You should pick ONE of the following, all
297 of which will continue my example setup from above:
299 As a mail alias pipe process
300 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
302 Set up a mail alias called "issue_tracker" as (include the quote marks):
303 "``|/usr/bin/python /usr/local/bin/roundup-mailgw <tracker_home>``"
305 In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh so
306 sendmail will accept the pipe command. In that case, symlink
307 ``/etc/smrsh/roundup-mailgw`` to "``/usr/local/bin/roundup-mailgw``" and change
308 the command to::
310 |roundup-mailgw /opt/roundup/trackers/support
312 To test the mail gateway on unix systems, try::
314 echo test |mail -s '[issue] test' support@YOUR_DOMAIN_HERE
316 As a regular cron job using a mailbox source
317 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
319 Set ``roundup-mailgw`` up to run every 10 minutes or so. For example::
321 10 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support mailbox <mail_spool_file>
323 Where the ``mail_spool_file`` argument is the location of the roundup submission
324 user's mail spool. On most systems, the spool for a user "issue_tracker"
325 will be "``/var/mail/issue_tracker``".
327 As a regular cron job using a POP source
328 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
330 To retrieve from a POP mailbox, use a similar cron entry to the mailbox one::
332 10 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support pop <pop_spec>
334 where pop_spec is "``username:password@server``" that specifies the roundup
335 submission user's POP account name, password and server.
338 Shared Environment Steps
339 ------------------------
341 Each tracker ideally should have its own UNIX group, so create
342 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
343 you're using NIS). To continue with my examples so far, I would
344 create the UNIX group 'support', although the name of the UNIX
345 group does not have to be the same as the tracker name. To this
346 'support' group I then add all of the UNIX usernames who will be
347 working with this Roundup tracker. In addition to 'real' users,
348 the Roundup email gateway will need to have permissions to this
349 area as well, so add the user your mail service runs as to the
350 group. The UNIX group might then look like::
352 support:*:1002:jblaine,samh,geezer,mail
354 If you intend to use the web interface (as most people do), you
355 should also add the username your web server runs as to the group.
356 My group now looks like this::
358 support:*:1002:jblaine,samh,geezer,mail,apache
360 The tracker "db" directory should be chmod'ed g+sw so that the group can
361 write to the database, and any new files created in the database will be owned
362 by the group.
364 An alternative to the above is to create a new user who has the sole
365 responsibility of running roundup. This user:
367 1. runs the CGI interface daemon
368 2. runs regular polls for email
369 3. runs regular checks (using cron) to ensure the daemon is up
370 4. optionally has no login password so that nobody but the "root" user
371 may actually login and play with the roundup setup.
374 Maintenance
375 ===========
377 Read the separate `maintenance documentation`_ for information about how to
378 perform common maintenance tasks with Roundup.
381 Upgrading
382 =========
384 Read the separate `upgrading document`_, which describes the steps needed to
385 upgrade existing tracker trackers for each version of Roundup that is
386 released.
389 Further Reading
390 ===============
392 If you intend to use Roundup with anything other than the defualt
393 templates, if you would like to hack on Roundup, or if you would
394 like implementation details, you should read `Customising Roundup`_.
397 Platform-Specific Notes
398 =======================
400 Sendmail smrsh
401 --------------
403 If you use Sendmail's ``smrsh`` mechanism, you will need to tell
404 smrsh that roundup-mailgw is a valid/trusted mail handler
405 before it will work.
407 This is usually done via the following 2 steps:
409 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
410 which points to the full path of your actual ``roundup-mailgw``
411 script.
413 2. change your alias to ``"|roundup-mailgw <tracker_home>"``
416 Linux
417 -----
419 Python 2.1.1 as shipped with SuSE7.3 might be missing module
420 ``_weakref``.
422 -------------------------------------------------------------------------------
424 Back to `Table of Contents`_
426 Next: `Getting Started`_
428 .. _`table of contents`: index.html
429 .. _`getting started`: getting_started.html
430 .. _`roundup specification`: spec.html
431 .. _`tracker configuration`: customizing.html#tracker-configuration
432 .. _`customisation documentation`: customizing.html
433 .. _`customising roundup`: customizing.html
434 .. _`upgrading document`: upgrading.html
435 .. _`maintenance documentation`: maintenance.html
436 .. _sqlite: http://www.hwaci.com/sw/sqlite/
437 .. _metakit: http://www.equi4.com/metakit/