Mercurial > p > roundup > code

annotate doc/installation.txt @ 1118:9b34d8a79d79 0.5.0-b1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
*** empty log message ***
author Richard Jones <richard@users.sourceforge.net>
date Wed, 11 Sep 2002 09:59:49 +0000
parents fa7df238e2d4
children af104fa52746
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
688
b38f4f95bffd More doc tweaks
Richard Jones <richard@users.sourceforge.net>
parents: 686
diff changeset
1 ==================
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2 Installing Roundup
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3 ==================
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
4
1096
fa7df238e2d4 More cleaning up of configuration, and the "instance" -> "tracker" renaming.
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
5 :Version: $Revision: 1.23 $
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
6
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
7 .. contents::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
8
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
9
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
10 Overview
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
11 ========
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
12
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
13 Broken out separately, there are several conceptual pieces to a
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
14 Roundup installation:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
15
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
16 Roundup support code
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
17 Installed into your Python install's lib directory
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
18
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
19 Roundup scripts
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
20 These include the email gateway, the roundup
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
21 HTTP server, the roundup administration command-line interface, etc.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
22
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
23 Roundup trackers
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
24 Trackers consist of core support files, issues
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
25 (be they bug reports or otherwise), tracker configuration file(s),
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
26 etc. Roundup trackers also adhere to a specific "Template" which
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
27 defines the fields usable/assignable on a per-issue basis. A
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
28 description of the provided templates follows.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
29
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
30 Classic Template
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
31 ----------------
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
32
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
33 The classic template is the one defined in the `Roundup Specification`_. It
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
34 holds issues which have priorities and statuses. Each issue may also have a
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
35 set of messages which are disseminated to the issue's list of nosy users.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
36
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
37
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
38 Extended Template
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
39 -----------------
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
40
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
41 The extended template adds additional information to issues: product,
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
42 platform, version, targetversion and supportcall.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
43 There is an additional class for
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
44 handling support calls, which includes a time log, customername, rate and
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
45 source.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
46
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
47 The priorty class has different default entries too: "fatal-bug", "bug",
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
48 "usability" and "feature".
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
49
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
50 Users of this template will want to change the contents of the product
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
51 class as soon as the tracker is created.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
52
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
53
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
54 Prerequisites
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
55 =============
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
56
727
779015e264b4 Note the version that is known to work.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
57 Python 2.1.1 or newer with a functioning anydbm or bsddb module. Download the
729
490bffefd5a0 "upgrade you doofus" text inserted to appease anthony ;)
Richard Jones <richard@users.sourceforge.net>
parents: 727
diff changeset
58 latest version from http://www.python.org/. It is highly recommended that
490bffefd5a0 "upgrade you doofus" text inserted to appease anthony ;)
Richard Jones <richard@users.sourceforge.net>
parents: 727
diff changeset
59 users install the latest patch version of python - 2.1.3 or 2.2.1 - as these
490bffefd5a0 "upgrade you doofus" text inserted to appease anthony ;)
Richard Jones <richard@users.sourceforge.net>
parents: 727
diff changeset
60 contain many fixes to serious bugs.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
61
727
779015e264b4 Note the version that is known to work.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
62 If you want to use Berkeley DB bsddb3 with Roundup, use version 3.3.0 or
779015e264b4 Note the version that is known to work.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
63 later. Download the latest version from http://pybsddb.sourceforge.net/.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
64
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
65
998
a1922b2521a7 reordering to make a little more sense
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
66 Getting Roundup
a1922b2521a7 reordering to make a little more sense
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
67 ===============
a1922b2521a7 reordering to make a little more sense
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
68
a1922b2521a7 reordering to make a little more sense
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
69 Download the latest version from http://roundup.sf.net/.
a1922b2521a7 reordering to make a little more sense
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
70
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
71 Testing your Python
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
72 -------------------
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
73
998
a1922b2521a7 reordering to make a little more sense
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
74 Once you've unpacked roundup's source, run ``python ./run_tests`` in the
a1922b2521a7 reordering to make a little more sense
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
75 source directory and make sure there are no errors.
a1922b2521a7 reordering to make a little more sense
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
76 If there are errors, please let us know!
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
77
798
faf164ab8ed9 Docco changes.
Richard Jones <richard@users.sourceforge.net>
parents: 782
diff changeset
78 If the above fails, you may be using the wrong version of python. Try
faf164ab8ed9 Docco changes.
Richard Jones <richard@users.sourceforge.net>
parents: 782
diff changeset
79 ``python2 ./run_tests``. If that works, you will need to substitute
faf164ab8ed9 Docco changes.
Richard Jones <richard@users.sourceforge.net>
parents: 782
diff changeset
80 ``python2`` for ``python`` in all further commands you use in relation to
faf164ab8ed9 Docco changes.
Richard Jones <richard@users.sourceforge.net>
parents: 782
diff changeset
81 Roundup -- from installation and scripts.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
82
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
83
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
84 Installation
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
85 ============
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
86
798
faf164ab8ed9 Docco changes.
Richard Jones <richard@users.sourceforge.net>
parents: 782
diff changeset
87 Set aside 15-30 minutes. Please make sure you're using a supported version of
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
88 Python -- see `testing your python`_. There's three sections to this
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
89 installation guide:
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
90
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
91 1. `basic installation steps`_ that all installers must follow
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
92 2. `shared environment steps`_ to take if you're installing on a shared
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
93 UNIX machine and want to restrict local access to roundup
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
94 3. `internet setup`_ steps to take if your tracker is to be used by the wider
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
95 internet community
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
96
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
97 Most users will only need to follow the first step, since the environment will
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
98 be a trusted one.
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
99
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
100
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
101 Basic Installation Steps
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
102 ------------------------
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
103
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
104 1. To install the Roundup support code into your Python tree and
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
105 Roundup scripts into /usr/local/bin::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
106
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
107 python setup.py install
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
108
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
109 If you would like to place the Roundup scripts in a directory other
1024
0fa94554443f *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1023
diff changeset
110 than ``/usr/local/bin``, then specify the preferred location with
1023
0161142aa903 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 998
diff changeset
111 ``--install-script``. For example, to install them in
0161142aa903 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 998
diff changeset
112 ``/opt/roundup/bin``::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
113
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
114 python setup.py install --install-scripts=/opt/roundup/bin
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
115
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
116 2. To create a Roundup tracker (necessary to do before you can
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
117 use the software in any real fashion):
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
118
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
119 a. (Optional) If you intend to keep your roundup trackers
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
120 under one top level directory which does not exist yet,
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
121 you should create that directory now. Example:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
122
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
123 mkdir /opt/roundup/trackers
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
124
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
125 b. Either add the Roundup script location to your ``PATH``
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
126 environment variable or specify the full path to
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
127 the command in the next step.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
128
738
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
129 c. ``roundup-admin install``
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
130
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
131 You will be asked a series of questions. A description of
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
132 the Roundup-provided templates can be found under the Overview_::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
133
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
134 Enter tracker home: /opt/roundup/trackers/support
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
135 Templates: classic, extended
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
136 Select template [classic]: classic
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
137 Back ends: anydbm, bsddb
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
138 Select backend [anydbm]: anydbm
738
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
139
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
140 You will now be directed to edit the tracker configuration and
741
b48a19a88b65 Cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 738
diff changeset
141 initial schema. See `Customising Roundup`_ for details on configuration
979
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 882
diff changeset
142 and schema changes. Note that you may change any of the configuration
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
143 after you've initialised the tracker - it's just better to have valid
979
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 882
diff changeset
144 values for this stuff now.
738
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
145
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
146 d. ``roundup-admin initialise``
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
147
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
148 This step initialises the tracker database. You will need to supply
979
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 882
diff changeset
149 an admin password at this step. You will be prompted::
738
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
150
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
151 Admin Password:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
152 Confirm:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
153
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
154 Once this is done, the tracker has been created.
738
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
155
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
156 3. XXX Set up the CGI interface
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
157
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
158 4. XXX Set up the mail gateway
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
159
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
160
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
161 Shared Environment Steps
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
162 ------------------------
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
163
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
164 Each tracker ideally should have its own UNIX group, so create
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
165 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
166 you're using NIS). To continue with my examples so far, I would
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
167 create the UNIX group 'support', although the name of the UNIX
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
168 group does not have to be the same as the tracker name. To this
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
169 'support' group I then add all of the UNIX usernames who will be
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
170 working with this Roundup tracker. In addition to 'real' users,
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
171 the Roundup email gateway will need to have permissions to this
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
172 area as well, so add the user your mail service runs as to the
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
173 group. The UNIX group might then look like::
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
174
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
175 support:*:1002:jblaine,samh,geezer,mail
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
176
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
177 If you intend to use the web interface (as most people do), you
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
178 should also add the username your web server runs as to the group.
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
179 My group now looks like this::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
180
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
181 support:*:1002:jblaine,samh,geezer,mail,apache
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
182
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
183 The tracker "db" directory should be chmod'ed g+sw so that the group can
1078
344bad728d10 more tweakage of help display and style issues
Richard Jones <richard@users.sourceforge.net>
parents: 1049
diff changeset
184 write to the database, and any new files created in the database will be owned
344bad728d10 more tweakage of help display and style issues
Richard Jones <richard@users.sourceforge.net>
parents: 1049
diff changeset
185 by the group.
344bad728d10 more tweakage of help display and style issues
Richard Jones <richard@users.sourceforge.net>
parents: 1049
diff changeset
186
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
187 An alternative to the above is to create a new user who has the sole
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
188 responsibility of running roundup. This user:
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
189
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
190 1. runs the CGI interface daemon
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
191 2. runs regular polls for email
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
192 3. runs regular checks (using cron) to ensure the daemon is up
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
193 4. optionally has no login password so that nobody but the "root" user
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
194 may actually login and play with the roundup setup.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
195
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
196 Internet Setup
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
197 --------------
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
198
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
199 1. There are two supported ways to get emailed issues into the
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
200 Roundup tracker. You should pick ONE of the following, both
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
201 of which will continue my example setup from above:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
202
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
203 a. Set up a mail alias called "support" as::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
204
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
205 "|/opt/roundup/bin/roundup-mailgw /opt/roundup/trackers/support"
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
206
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
207 If you use Sendmail's ``smrsh`` mechanism, please read the notes
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
208 under 'Platform-Specific Notes'
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
209
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
210 b. OR... Configure roundup-mailgw to run every 10 minutes or
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
211 so via ``cron``. My cron job would be (these 2 lines all on one
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
212 line)::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
213
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
214 10 * * * * /opt/roundup/bin/roundup-mailgw
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
215 /opt/roundup/trackers/support /var/mail/support
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
216
1023
0161142aa903 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 998
diff changeset
217 If you don't want to use the email component of Roundup, then remove the
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
218 "``nosyreator.py``" module from your tracker "``detectors``" directory.
1023
0161142aa903 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 998
diff changeset
219
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
220 2. Test the email gateway. Under most flavors of UNIX, this
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
221 can be done by::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
222
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
223 echo test | mail -s '[issue] test' support@YOUR_DOMAIN_HERE
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
224
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
225 XXX mention HTTPS
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
226 XXX mention Basic vs. cookie auth
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
227
782
6f6eb43d9d86 Moved the MIGRATION text in with the rest of the docco, fixed up for 0.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
228
6f6eb43d9d86 Moved the MIGRATION text in with the rest of the docco, fixed up for 0.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
229 Upgrading
6f6eb43d9d86 Moved the MIGRATION text in with the rest of the docco, fixed up for 0.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
230 =========
6f6eb43d9d86 Moved the MIGRATION text in with the rest of the docco, fixed up for 0.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
231
882
b99948d32a2d clearing up ambiguous ref name
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
232 Read the separate `upgrading document`_, which describes the steps needed to
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
233 upgrade existing tracker trackers for each version of Roundup that is
782
6f6eb43d9d86 Moved the MIGRATION text in with the rest of the docco, fixed up for 0.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
234 released.
6f6eb43d9d86 Moved the MIGRATION text in with the rest of the docco, fixed up for 0.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
235
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
236
724
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
237 ZRoundup
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
238 ========
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
239
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
240 Install roundup as usual (see installation_).
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
241
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
242 ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
1096
fa7df238e2d4 More cleaning up of configuration, and the "instance" -> "tracker" renaming.
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
243 your Products directory either in an TRACKER_HOME/Products or the Zope
724
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
244 code tree lib/python/Products.
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
245
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
246 You will need to create the tracker using the roundup-admin tool (step 2 in
724
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
247 installation_).
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
248
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
249 When you next (re)start up Zope, you will be able to add a ZRoundup object
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
250 that interfaces to your new tracker.
724
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
251
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
252
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
253 Further Reading
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
254 ===============
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
255
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
256 If you intend to use Roundup with anything other than the defualt
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
257 templates, if you would like to hack on Roundup, or if you would
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
258 like implementation details, you should read `Customising Roundup`_.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
259
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
260
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
261 Platform-Specific Notes
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
262 =======================
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
263
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
264 Sendmail smrsh
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
265 --------------
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
266
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
267 If you use Sendmail's ``smrsh`` mechanism, you will need to tell
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
268 smrsh that roundup-mailgw is a valid/trusted mail handler
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
269 before it will work.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
270
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
271 This is usually done via the following 2 steps:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
272
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
273 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
274 which points to the full path of your actual ``roundup-mailgw``
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
275 script.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
276
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
277 2. change your alias to ``"|roundup-mailgw <tracker_home>"``
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
278
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
279
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
280 Linux
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
281 -----
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
282
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
283 Python 2.1.1 as shipped with SuSE7.3 might be missing module
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
284 ``_weakref``.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
285
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
286 -------------------------------------------------------------------------------
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
287
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
288 Back to `Table of Contents`_
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
289
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
290 Next: `Getting Started`_
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
291
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
292 .. _`table of contents`: index.html
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
293 .. _`getting started`: getting_started.html
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
294 .. _`roundup specification`: spec.html
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
295 .. _`customising roundup`: customizing.html
882
b99948d32a2d clearing up ambiguous ref name
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
296 .. _`upgrading document`: upgrading.html
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
297
Roundup Issue Tracker: http://roundup-tracker.org/