Mercurial > p > roundup > code

comparison doc/installation.txt @ 1089:43ab730ee194

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
instance -> tracker, node -> item
author Richard Jones <richard@users.sourceforge.net>
date Tue, 10 Sep 2002 00:15:59 +0000
parents 344bad728d10
children fa7df238e2d4
comparison
equal deleted inserted replaced
1088:32e41ddf2edb 1089:43ab730ee194
1 ================== 1 ==================
2 Installing Roundup 2 Installing Roundup
3 ================== 3 ==================
4 4
5 :Version: $Revision: 1.21 $ 5 :Version: $Revision: 1.22 $
6 6
7 .. contents:: 7 .. contents::
8 8
9 9
10 Overview 10 Overview
18 18
19 Roundup scripts 19 Roundup scripts
20 These include the email gateway, the roundup 20 These include the email gateway, the roundup
21 HTTP server, the roundup administration command-line interface, etc. 21 HTTP server, the roundup administration command-line interface, etc.
22 22
23 Roundup instances 23 Roundup trackers
24 Instances consist of core support files, issues 24 Trackers consist of core support files, issues
25 (be they bug reports or otherwise), instance configuration file(s), 25 (be they bug reports or otherwise), tracker configuration file(s),
26 etc. Roundup instances also adhere to a specific "Template" which 26 etc. Roundup trackers also adhere to a specific "Template" which
27 defines the fields usable/assignable on a per-issue basis. A 27 defines the fields usable/assignable on a per-issue basis. A
28 description of the provided templates follows. 28 description of the provided templates follows.
29 29
30 Classic Template 30 Classic Template
31 ---------------- 31 ----------------
46 46
47 The priorty class has different default entries too: "fatal-bug", "bug", 47 The priorty class has different default entries too: "fatal-bug", "bug",
48 "usability" and "feature". 48 "usability" and "feature".
49 49
50 Users of this template will want to change the contents of the product 50 Users of this template will want to change the contents of the product
51 class as soon as the instance is created. 51 class as soon as the tracker is created.
52 52
53 53
54 Prerequisites 54 Prerequisites
55 ============= 55 =============
56 56
97 Most users will only need to follow the first step, since the environment will 97 Most users will only need to follow the first step, since the environment will
98 be a trusted one. 98 be a trusted one.
99 99
100 100
101 Basic Installation Steps 101 Basic Installation Steps
102 ~~~~~~~~~~~~~~~~~~~~~~~~ 102 ------------------------
103 103
104 1. To install the Roundup support code into your Python tree and 104 1. To install the Roundup support code into your Python tree and
105 Roundup scripts into /usr/local/bin:: 105 Roundup scripts into /usr/local/bin::
106 106
107 python setup.py install 107 python setup.py install
111 ``--install-script``. For example, to install them in 111 ``--install-script``. For example, to install them in
112 ``/opt/roundup/bin``:: 112 ``/opt/roundup/bin``::
113 113
114 python setup.py install --install-scripts=/opt/roundup/bin 114 python setup.py install --install-scripts=/opt/roundup/bin
115 115
116 2. To create a Roundup instance (necessary to do before you can 116 2. To create a Roundup tracker (necessary to do before you can
117 use the software in any real fashion): 117 use the software in any real fashion):
118 118
119 a. (Optional) If you intend to keep your roundup instances 119 a. (Optional) If you intend to keep your roundup trackers
120 under one top level directory which does not exist yet, 120 under one top level directory which does not exist yet,
121 you should create that directory now. Example: 121 you should create that directory now. Example:
122 122
123 mkdir /opt/roundup/instances 123 mkdir /opt/roundup/trackers
124 124
125 b. Either add the Roundup script location to your ``PATH`` 125 b. Either add the Roundup script location to your ``PATH``
126 environment variable or specify the full path to 126 environment variable or specify the full path to
127 the command in the next step. 127 the command in the next step.
128 128
129 c. ``roundup-admin install`` 129 c. ``roundup-admin install``
130 130
131 You will be asked a series of questions. A description of 131 You will be asked a series of questions. A description of
132 the Roundup-provided templates can be found under the Overview_:: 132 the Roundup-provided templates can be found under the Overview_::
133 133
134 Enter instance home: /opt/roundup/instances/support 134 Enter tracker home: /opt/roundup/trackers/support
135 Templates: classic, extended 135 Templates: classic, extended
136 Select template [classic]: classic 136 Select template [classic]: classic
137 Back ends: anydbm, bsddb 137 Back ends: anydbm, bsddb
138 Select backend [anydbm]: anydbm 138 Select backend [anydbm]: anydbm
139 139
140 You will now be directed to edit the instance configuration and 140 You will now be directed to edit the tracker configuration and
141 initial schema. See `Customising Roundup`_ for details on configuration 141 initial schema. See `Customising Roundup`_ for details on configuration
142 and schema changes. Note that you may change any of the configuration 142 and schema changes. Note that you may change any of the configuration
143 after you've initialised the instance - it's just better to have valid 143 after you've initialised the tracker - it's just better to have valid
144 values for this stuff now. 144 values for this stuff now.
145 145
146 d. ``roundup-admin initialise`` 146 d. ``roundup-admin initialise``
147 147
148 This step initialises the instance database. You will need to supply 148 This step initialises the tracker database. You will need to supply
149 an admin password at this step. You will be prompted:: 149 an admin password at this step. You will be prompted::
150 150
151 Admin Password: 151 Admin Password:
152 Confirm: 152 Confirm:
153 153
154 Once this is done, the instance has been created. 154 Once this is done, the tracker has been created.
155 155
156 3. XXX Set up the CGI interface 156 3. XXX Set up the CGI interface
157 157
158 4. XXX Set up the mail gateway 158 4. XXX Set up the mail gateway
159 159
160 160
161 Shared Environment Steps 161 Shared Environment Steps
162 ~~~~~~~~~~~~~~~~~~~~~~~~ 162 ------------------------
163 163
164 Each instance ideally should have its own UNIX group, so create 164 Each tracker ideally should have its own UNIX group, so create
165 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if 165 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
166 you're using NIS). To continue with my examples so far, I would 166 you're using NIS). To continue with my examples so far, I would
167 create the UNIX group 'support', although the name of the UNIX 167 create the UNIX group 'support', although the name of the UNIX
168 group does not have to be the same as the instance name. To this 168 group does not have to be the same as the tracker name. To this
169 'support' group I then add all of the UNIX usernames who will be 169 'support' group I then add all of the UNIX usernames who will be
170 working with this Roundup instance. In addition to 'real' users, 170 working with this Roundup tracker. In addition to 'real' users,
171 the Roundup email gateway will need to have permissions to this 171 the Roundup email gateway will need to have permissions to this
172 area as well, so add the user your mail service runs as to the 172 area as well, so add the user your mail service runs as to the
173 group. The UNIX group might then look like:: 173 group. The UNIX group might then look like::
174 174
175 support:*:1002:jblaine,samh,geezer,mail 175 support:*:1002:jblaine,samh,geezer,mail
178 should also add the username your web server runs as to the group. 178 should also add the username your web server runs as to the group.
179 My group now looks like this:: 179 My group now looks like this::
180 180
181 support:*:1002:jblaine,samh,geezer,mail,apache 181 support:*:1002:jblaine,samh,geezer,mail,apache
182 182
183 The instance "db" directory should be chmod'ed g+sw so that the group can 183 The tracker "db" directory should be chmod'ed g+sw so that the group can
184 write to the database, and any new files created in the database will be owned 184 write to the database, and any new files created in the database will be owned
185 by the group. 185 by the group.
186 186
187 An alternative to the above is to create a new user who has the sole 187 An alternative to the above is to create a new user who has the sole
188 responsibility of running roundup. This user: 188 responsibility of running roundup. This user:
192 3. runs regular checks (using cron) to ensure the daemon is up 192 3. runs regular checks (using cron) to ensure the daemon is up
193 4. optionally has no login password so that nobody but the "root" user 193 4. optionally has no login password so that nobody but the "root" user
194 may actually login and play with the roundup setup. 194 may actually login and play with the roundup setup.
195 195
196 Internet Setup 196 Internet Setup
197 ~~~~~~~~~~~~~~ 197 --------------
198 198
199 1. There are two supported ways to get emailed issues into the 199 1. There are two supported ways to get emailed issues into the
200 Roundup instance. You should pick ONE of the following, both 200 Roundup tracker. You should pick ONE of the following, both
201 of which will continue my example setup from above: 201 of which will continue my example setup from above:
202 202
203 a. Set up a mail alias called "support" as:: 203 a. Set up a mail alias called "support" as::
204 204
205 "|/opt/roundup/bin/roundup-mailgw /opt/roundup/instances/support" 205 "|/opt/roundup/bin/roundup-mailgw /opt/roundup/trackers/support"
206 206
207 If you use Sendmail's ``smrsh`` mechanism, please read the notes 207 If you use Sendmail's ``smrsh`` mechanism, please read the notes
208 under 'Platform-Specific Notes' 208 under 'Platform-Specific Notes'
209 209
210 b. OR... Configure roundup-mailgw to run every 10 minutes or 210 b. OR... Configure roundup-mailgw to run every 10 minutes or
211 so via ``cron``. My cron job would be (these 2 lines all on one 211 so via ``cron``. My cron job would be (these 2 lines all on one
212 line):: 212 line)::
213 213
214 10 * * * * /opt/roundup/bin/roundup-mailgw 214 10 * * * * /opt/roundup/bin/roundup-mailgw
215 /opt/roundup/instances/support /var/mail/support 215 /opt/roundup/trackers/support /var/mail/support
216 216
217 If you don't want to use the email component of Roundup, then remove the 217 If you don't want to use the email component of Roundup, then remove the
218 "``nosyreator.py``" module from your instance "``detectors``" directory. 218 "``nosyreator.py``" module from your tracker "``detectors``" directory.
219 219
220 2. Test the email gateway. Under most flavors of UNIX, this 220 2. Test the email gateway. Under most flavors of UNIX, this
221 can be done by:: 221 can be done by::
222 222
223 echo test | mail -s '[issue] test' support@YOUR_DOMAIN_HERE 223 echo test | mail -s '[issue] test' support@YOUR_DOMAIN_HERE
228 228
229 Upgrading 229 Upgrading
230 ========= 230 =========
231 231
232 Read the separate `upgrading document`_, which describes the steps needed to 232 Read the separate `upgrading document`_, which describes the steps needed to
233 upgrade existing tracker instances for each version of Roundup that is 233 upgrade existing tracker trackers for each version of Roundup that is
234 released. 234 released.
235 235
236 236
237 ZRoundup 237 ZRoundup
238 ======== 238 ========
241 241
242 ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to 242 ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
243 your Products directory either in an INSTANCE_HOME/Products or the Zope 243 your Products directory either in an INSTANCE_HOME/Products or the Zope
244 code tree lib/python/Products. 244 code tree lib/python/Products.
245 245
246 You will need to create the instance using the roundup-admin tool (step 2 in 246 You will need to create the tracker using the roundup-admin tool (step 2 in
247 installation_). 247 installation_).
248 248
249 When you next (re)start up Zope, you will be able to add a ZRoundup object 249 When you next (re)start up Zope, you will be able to add a ZRoundup object
250 that interfaces to your new instance. 250 that interfaces to your new tracker.
251 251
252 252
253 Further Reading 253 Further Reading
254 =============== 254 ===============
255 255
272 272
273 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw`` 273 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
274 which points to the full path of your actual ``roundup-mailgw`` 274 which points to the full path of your actual ``roundup-mailgw``
275 script. 275 script.
276 276
277 2. change your alias to ``"|roundup-mailgw <instance_home>"`` 277 2. change your alias to ``"|roundup-mailgw <tracker_home>"``
278 278
279 279
280 Linux 280 Linux
281 ----- 281 -----
282 282
Roundup Issue Tracker: http://roundup-tracker.org/