1 ==================
2 Installing Roundup
3 ==================
5 :Version: $Revision: 1.19 $
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 Getting Roundup
67 ===============
69 Download the latest version from http://roundup.sf.net/.
71 Testing your Python
72 -------------------
74 Once you've unpacked roundup's source, run ``python ./run_tests`` in the
75 source directory and make sure there are no errors.
76 If there are errors, please let us know!
78 If the above fails, you may be using the wrong version of python. Try
79 ``python2 ./run_tests``. If that works, you will need to substitute
80 ``python2`` for ``python`` in all further commands you use in relation to
81 Roundup -- from installation and scripts.
84 Installation
85 ============
87 Set aside 15-30 minutes. Please make sure you're using a supported version of
88 Python -- see `testing your python`_.
90 1. To install the Roundup support code into your Python tree and
91 Roundup scripts into /usr/local/bin::
93 python setup.py install
95 If you would like to place the Roundup scripts in a directory other
96 than ``/usr/local/bin``, then specify the preferred location with
97 ``--install-script``. For example, to install them in
98 ``/opt/roundup/bin``::
100 python setup.py install --install-scripts=/opt/roundup/bin
102 2. To create a Roundup instance (necessary to do before you can
103 use the software in any real fashion):
105 a. (Optional) If you intend to keep your roundup instances
106 under one top level directory which does not exist yet,
107 you should create that directory now. Example:
109 mkdir /opt/roundup/instances
111 b. Either add the Roundup script location to your ``PATH``
112 environment variable or specify the full path to
113 the command in the next step.
115 c. ``roundup-admin install``
117 You will be asked a series of questions. A description of
118 the Roundup-provided templates can be found under the Overview_::
120 Enter instance home: /opt/roundup/instances/support
121 Templates: classic, extended
122 Select template [classic]: classic
123 Back ends: anydbm, bsddb
124 Select backend [anydbm]: anydbm
126 You will now be directed to edit the instance configuration and
127 initial schema. See `Customising Roundup`_ for details on configuration
128 and schema changes. Note that you may change any of the configuration
129 after you've initialised the instance - it's just better to have valid
130 values for this stuff now.
132 d. ``roundup-admin initialise``
134 This step initialises the instance database. You will need to supply
135 an admin password at this step. You will be prompted::
137 Admin Password:
138 Confirm:
140 Once this is done, the instance has been created.
142 3. Each instance ideally should have its own UNIX group, so create
143 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
144 you're using NIS). To continue with my examples so far, I would
145 create the UNIX group 'support', although the name of the UNIX
146 group does not have to be the same as the instance name. To this
147 'support' group I then add all of the UNIX usernames who will be
148 working with this Roundup instance. In addition to 'real' users,
149 the Roundup email gateway will need to have permissions to this
150 area as well, so add the user your mail service runs as to the
151 group. The UNIX group might then look like::
153 support:*:1002:jblaine,samh,geezer,mail
155 If you intend to use the web interface (as most people do), you
156 should also add the username your web server runs as to the group.
157 My group now looks like this::
159 support:*:1002:jblaine,samh,geezer,mail,apache
161 4. Configure your new instance by editing the file ``instance_config.py``
162 located in the instance home you specified in step 2c above. This
163 file is Python code and must adhere to Python syntax rules, but
164 don't be daunted if you do not know Python - it should look pretty
165 straightfoward if you carefully read the comments in the file.
167 5. There are two supported ways to get emailed issues into the
168 Roundup instance. You should pick ONE of the following, both
169 of which will continue my example setup from above:
171 a. Set up a mail alias called "support" as::
173 "|/opt/roundup/bin/roundup-mailgw /opt/roundup/instances/support"
175 If you use Sendmail's ``smrsh`` mechanism, please read the notes
176 under 'Platform-Specific Notes'
178 b. OR... Configure roundup-mailgw to run every 10 minutes or
179 so via ``cron``. My cron job would be (these 2 lines all on one
180 line)::
182 10 * * * * /opt/roundup/bin/roundup-mailgw
183 /opt/roundup/instances/support /var/mail/support
185 If you don't want to use the email component of Roundup, then remove the
186 "``nosyreator.py``" module from your instance "``detectors``" directory.
188 6. Test the email gateway. Under most flavors of UNIX, this
189 can be done by::
191 echo test | mail -s '[issue] test' support@YOUR_DOMAIN_HERE
194 Upgrading
195 =========
197 Read the separate `upgrading document`_, which describes the steps needed to
198 upgrade existing tracker instances for each version of Roundup that is
199 released.
202 ZRoundup
203 ========
205 Install roundup as usual (see installation_).
207 ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
208 your Products directory either in an INSTANCE_HOME/Products or the Zope
209 code tree lib/python/Products.
211 You will need to create the instance using the roundup-admin tool (step 2 in
212 installation_).
214 When you next (re)start up Zope, you will be able to add a ZRoundup object
215 that interfaces to your new instance.
218 Further Reading
219 ===============
221 If you intend to use Roundup with anything other than the defualt
222 templates, if you would like to hack on Roundup, or if you would
223 like implementation details, you should read `Customising Roundup`_.
226 Platform-Specific Notes
227 =======================
229 Sendmail smrsh
230 --------------
232 If you use Sendmail's ``smrsh`` mechanism, you will need to tell
233 smrsh that roundup-mailgw is a valid/trusted mail handler
234 before it will work.
236 This is usually done via the following 2 steps:
238 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
239 which points to the full path of your actual ``roundup-mailgw``
240 script.
242 2. change your alias to ``"|roundup-mailgw <instance_home>"``
245 Linux
246 -----
248 Python 2.1.1 as shipped with SuSE7.3 might be missing module
249 ``_weakref``.
251 -------------------------------------------------------------------------------
253 Back to `Table of Contents`_
255 Next: `Getting Started`_
257 .. _`table of contents`: index.html
258 .. _`getting started`: getting_started.html
259 .. _`roundup specification`: spec.html
260 .. _`customising roundup`: customizing.html
261 .. _`upgrading document`: upgrading.html