908cd59fb8ad2ce0d8964eaa8bc0f83411676004
1 ==================
2 Installing Roundup
3 ==================
5 :Version: $Revision: 1.10 $
7 .. contents::
10 Overview
11 ========
13 Broken out separately, there are several conceptual pieces to a
14 Roundup installation:
16 Roundup support code
17 Installed into your Python install's lib directory
19 Roundup scripts
20 These include the email gateway, the roundup
21 HTTP server, the roundup administration command-line interface, etc.
23 Roundup instances
24 Instances consist of core support files, issues
25 (be they bug reports or otherwise), instance configuration file(s),
26 etc. Roundup instances also adhere to a specific "Template" which
27 defines the fields usable/assignable on a per-issue basis. A
28 description of the provided templates follows.
30 Classic Template
31 ----------------
33 The classic template is the one defined in the `Roundup Specification`_. It
34 holds issues which have priorities and statuses. Each issue may also have a
35 set of messages which are disseminated to the issue's list of nosy users.
38 Extended Template
39 -----------------
41 The extended template adds additional information to issues: product,
42 platform, version, targetversion and supportcall.
43 There is an additional class for
44 handling support calls, which includes a time log, customername, rate and
45 source.
47 The priorty class has different default entries too: "fatal-bug", "bug",
48 "usability" and "feature".
50 Users of this template will want to change the contents of the product
51 class as soon as the instance is created.
54 Prerequisites
55 =============
57 Python 2.1.1 or newer with a functioning anydbm or bsddb module. Download the
58 latest version from http://www.python.org/. It is highly recommended that
59 users install the latest patch version of python - 2.1.3 or 2.2.1 - as these
60 contain many fixes to serious bugs.
62 If you want to use Berkeley DB bsddb3 with Roundup, use version 3.3.0 or
63 later. Download the latest version from http://pybsddb.sourceforge.net/.
66 Testing your Python
67 -------------------
69 Run ``"python ./run_tests"`` and make sure there
70 are no errors. If there are errors, please let us know!
72 Note: if you're installing from the CVS, you will need to run "python setup.py
73 build" before the tests will work, as there are modules that must be
74 generated that are not stored in the CVS.
77 Getting Roundup
78 ===============
80 Download the latest version from http://roundup.sf.net/.
83 Installation
84 ============
86 Set aside 15-30 minutes.
88 1. To install the Roundup support code into your Python tree and
89 Roundup scripts into /usr/local/bin::
91 python setup.py install
93 If you would like to place the Roundup scripts in a directory other
94 than ``/usr/local/bin``, use the ``--install-scripts`` option as follows,
95 replacing ``/opt/roundup/bin`` with the location where you would like
96 the scripts to reside::
98 python setup.py install --install-scripts=/opt/roundup/bin
100 2. To create a Roundup instance (necessary to do before you can
101 use the software in any real fashion):
103 a. (Optional) If you intend to keep your roundup instances
104 under one top level directory which does not exist yet,
105 you should create that directory now. Example:
107 mkdir /opt/roundup/instances
109 b. Either add the Roundup script location to your ``PATH``
110 environment variable or specify the full path to
111 the command in the next step.
113 c. ``roundup-admin install``
115 You will be asked a series of questions. A description of
116 the Roundup-provided templates can be found under the Overview_::
118 Enter instance home: /opt/roundup/instances/support
119 Templates: classic, extended
120 Select template [classic]: classic
121 Back ends: anydbm, bsddb
122 Select backend [anydbm]: anydbm
124 You will now be directed to edit the instance configuration and
125 initial schema. See `Customising Roundup`_ for details on configuration
126 and schema changes.
128 d. ``roundup-admin initialise``
130 This step initialises the instance database. You will need to supply
131 an admin password at this step. You will be prompted:
133 Admin Password:
134 Confirm:
136 Once this is done, the instance has been created.
138 3. Each instance ideally should have its own UNIX group, so create
139 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
140 you're using NIS). To continue with my examples so far, I would
141 create the UNIX group 'support', although the name of the UNIX
142 group does not have to be the same as the instance name. To this
143 'support' group I then add all of the UNIX usernames who will be
144 working with this Roundup instance. In addition to 'real' users,
145 the Roundup email gateway will need to have permissions to this
146 area as well, so add the user your mail service runs as to the
147 group. The UNIX group might then look like::
149 support:*:1002:jblaine,samh,geezer,mail
151 If you intend to use the web interface (as most people do), you
152 should also add the username your web server runs as to the group.
153 My group now looks like this::
155 support:*:1002:jblaine,samh,geezer,mail,apache
157 4. Configure your new instance by editing the file ``instance_config.py``
158 located in the instance home you specified in step 2c above. This
159 file is Python code and must adhere to Python syntax rules, but
160 don't be daunted if you do not know Python - it should look pretty
161 straightfoward if you carefully read the comments in the file.
163 5. There are two supported ways to get emailed issues into the
164 Roundup instance. You should pick ONE of the following, both
165 of which will continue my example setup from above:
167 a. Set up a mail alias called "support" as::
169 "|/opt/roundup/bin/roundup-mailgw /opt/roundup/instances/support"
171 If you use Sendmail's ``smrsh`` mechanism, please read the notes
172 under 'Platform-Specific Notes'
174 b. OR... Configure roundup-mailgw to run every 10 minutes or
175 so via ``cron``. My cron job would be (these 2 lines all on one
176 line)::
178 10 * * * * /opt/roundup/bin/roundup-mailgw
179 /opt/roundup/instances/support /var/mail/support
181 6. TODO (mention perms)
183 7. Test the email gateway. Under most flavors of UNIX, this
184 can be done by::
186 echo test | mail -s '[issue] test' support@YOUR_DOMAIN_HERE
188 TODO (finish)
190 ZRoundup
191 ========
193 Install roundup as usual (see installation_).
195 ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
196 your Products directory either in an INSTANCE_HOME/Products or the Zope
197 code tree lib/python/Products.
199 You will need to create the instance using the roundup-admin tool (step 2 in
200 installation_).
202 When you next (re)start up Zope, you will be able to add a ZRoundup object
203 that interfaces to your new instance.
206 Further Reading
207 ===============
209 If you intend to use Roundup with anything other than the defualt
210 templates, if you would like to hack on Roundup, or if you would
211 like implementation details, you should read `Customising Roundup`_.
214 Platform-Specific Notes
215 =======================
217 Sendmail smrsh
218 --------------
220 If you use Sendmail's ``smrsh`` mechanism, you will need to tell
221 smrsh that roundup-mailgw is a valid/trusted mail handler
222 before it will work.
224 This is usually done via the following 2 steps:
226 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
227 which points to the full path of your actual ``roundup-mailgw``
228 script.
230 2. change your alias to ``"|roundup-mailgw <instance_home>"``
233 Linux
234 -----
236 Python 2.1.1 as shipped with SuSE7.3 might be missing module
237 ``_weakref``.
239 -------------------------------------------------------------------------------
241 Back to `Table of Contents`_
243 Next: `Getting Started`_
245 .. _`table of contents`: index.html
246 .. _`getting started`: getting_started.html
247 .. _`roundup specification`: spec.html
248 .. _`customising roundup`: customizing.html