Mercurial > p > roundup > code

annotate doc/installation.txt @ 1020:9513228a409a maint-0.4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
documentation quibble
author Richard Jones <richard@users.sourceforge.net>
date Tue, 03 Sep 2002 03:32:54 +0000
parents 08858c7be257
children 71fa12d26d4f
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
1020
9513228a409a documentation quibble
Richard Jones <richard@users.sourceforge.net>
parents: 845
diff changeset
5 :Version: $Revision: 1.13.2.3 $
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
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
23 Roundup instances
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
24 Instances consist of core support files, issues
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
25 (be they bug reports or otherwise), instance configuration file(s),
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
26 etc. Roundup instances also adhere to a specific "Template" which
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
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
51 class as soon as the instance is created.
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
845
08858c7be257 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
62 You will need to have the zlib/gzip modules available to python.
08858c7be257 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
63
727
779015e264b4 Note the version that is known to work.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
64 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
65 later. Download the latest version from http://pybsddb.sourceforge.net/.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
66
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
67
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
68 Testing your Python
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
69 -------------------
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
70
798
faf164ab8ed9 Docco changes.
Richard Jones <richard@users.sourceforge.net>
parents: 782
diff changeset
71 Run ``python ./run_tests`` and make sure there
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
72 are no errors. If there are errors, please let us know!
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
73
798
faf164ab8ed9 Docco changes.
Richard Jones <richard@users.sourceforge.net>
parents: 782
diff changeset
74 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
75 ``python2 ./run_tests``. If that works, you will need to substitute
faf164ab8ed9 Docco changes.
Richard Jones <richard@users.sourceforge.net>
parents: 782
diff changeset
76 ``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
77 Roundup -- from installation and scripts.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
78
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
79 Getting Roundup
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
80 ===============
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
81
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
82 Download the latest version from http://roundup.sf.net/.
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
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
85 Installation
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
86 ============
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
87
798
faf164ab8ed9 Docco changes.
Richard Jones <richard@users.sourceforge.net>
parents: 782
diff changeset
88 Set aside 15-30 minutes. Please make sure you're using a supported version of
faf164ab8ed9 Docco changes.
Richard Jones <richard@users.sourceforge.net>
parents: 782
diff changeset
89 Python -- see `testing your python`_.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
90
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
91 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
92 Roundup scripts into /usr/local/bin::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
93
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
94 python setup.py install
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
95
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
96 If you would like to place the Roundup scripts in a directory other
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
97 than ``/usr/local/bin``, use the ``--install-scripts`` option as follows,
1020
9513228a409a documentation quibble
Richard Jones <richard@users.sourceforge.net>
parents: 845
diff changeset
98 replacing ``/opt/roundup/bin`` in the following command with the location
9513228a409a documentation quibble
Richard Jones <richard@users.sourceforge.net>
parents: 845
diff changeset
99 where you would like the scripts to reside::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
100
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
101 python setup.py install --install-scripts=/opt/roundup/bin
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
102
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
103 2. To create a Roundup instance (necessary to do before you can
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
104 use the software in any real fashion):
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
105
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
106 a. (Optional) If you intend to keep your roundup instances
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
107 under one top level directory which does not exist yet,
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
108 you should create that directory now. Example:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
109
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
110 mkdir /opt/roundup/instances
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
111
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
112 b. Either add the Roundup script location to your ``PATH``
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
113 environment variable or specify the full path to
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
114 the command in the next step.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
115
738
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
116 c. ``roundup-admin install``
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
117
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
118 You will be asked a series of questions. A description of
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
119 the Roundup-provided templates can be found under the Overview_::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
120
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
121 Enter instance home: /opt/roundup/instances/support
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
122 Templates: classic, extended
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
123 Select template [classic]: classic
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
124 Back ends: anydbm, bsddb
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
125 Select backend [anydbm]: anydbm
738
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
126
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
127 You will now be directed to edit the instance configuration and
741
b48a19a88b65 Cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 738
diff changeset
128 initial schema. See `Customising Roundup`_ for details on configuration
738
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
129 and schema changes.
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
130
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
131 d. ``roundup-admin initialise``
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
132
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
133 This step initialises the instance database. You will need to supply
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
134 an admin password at this step. You will be prompted:
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
135
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
136 Admin Password:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
137 Confirm:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
138
738
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
139 Once this is done, the instance has been created.
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
140
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
141 3. Each instance ideally should have its own UNIX group, so create
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
142 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
143 you're using NIS). To continue with my examples so far, I would
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
144 create the UNIX group 'support', although the name of the UNIX
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
145 group does not have to be the same as the instance name. To this
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
146 'support' group I then add all of the UNIX usernames who will be
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
147 working with this Roundup instance. In addition to 'real' users,
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
148 the Roundup email gateway will need to have permissions to this
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
149 area as well, so add the user your mail service runs as to the
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
150 group. The UNIX group might then look like::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
151
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
152 support:*:1002:jblaine,samh,geezer,mail
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
153
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
154 If you intend to use the web interface (as most people do), you
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
155 should also add the username your web server runs as to the group.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
156 My group now looks like this::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
157
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
158 support:*:1002:jblaine,samh,geezer,mail,apache
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
159
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
160 4. Configure your new instance by editing the file ``instance_config.py``
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
161 located in the instance home you specified in step 2c above. This
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
162 file is Python code and must adhere to Python syntax rules, but
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
163 don't be daunted if you do not know Python - it should look pretty
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
164 straightfoward if you carefully read the comments in the file.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
165
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
166 5. There are two supported ways to get emailed issues into the
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
167 Roundup instance. You should pick ONE of the following, both
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
168 of which will continue my example setup from above:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
169
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
170 a. Set up a mail alias called "support" as::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
171
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
172 "|/opt/roundup/bin/roundup-mailgw /opt/roundup/instances/support"
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
173
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
174 If you use Sendmail's ``smrsh`` mechanism, please read the notes
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
175 under 'Platform-Specific Notes'
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
176
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
177 b. OR... Configure roundup-mailgw to run every 10 minutes or
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
178 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
179 line)::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
180
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
181 10 * * * * /opt/roundup/bin/roundup-mailgw
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
182 /opt/roundup/instances/support /var/mail/support
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
183
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
184 6. TODO (mention perms)
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
185
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
186 7. Test the email gateway. Under most flavors of UNIX, this
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
187 can be done by::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
188
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
189 echo test | mail -s '[issue] test' support@YOUR_DOMAIN_HERE
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
190
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
191
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
192 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
193 =========
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
194
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
195 Read the separate upgrading_ document, which describes the steps needed to
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
196 upgrade existing tracker instances for each version of Roundup that is
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
197 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
198
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
199
724
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
200 ZRoundup
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
201 ========
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
202
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
203 Install roundup as usual (see installation_).
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
204
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
205 ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
206 your Products directory either in an INSTANCE_HOME/Products or the Zope
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
207 code tree lib/python/Products.
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
208
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
209 You will need to create the instance using the roundup-admin tool (step 2 in
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
210 installation_).
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
211
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
212 When you next (re)start up Zope, you will be able to add a ZRoundup object
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
213 that interfaces to your new instance.
0085e1d718c4 Made ZRoundup install info more accessible.
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
214
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
215
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
216 Further Reading
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
217 ===============
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
218
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
219 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
220 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
221 like implementation details, you should read `Customising Roundup`_.
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
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
224 Platform-Specific Notes
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
225 =======================
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
226
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
227 Sendmail smrsh
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
228 --------------
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
229
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
230 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
231 smrsh that roundup-mailgw is a valid/trusted mail handler
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
232 before it will work.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
233
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
234 This is usually done via the following 2 steps:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
235
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
236 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
237 which points to the full path of your actual ``roundup-mailgw``
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
238 script.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
239
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
240 2. change your alias to ``"|roundup-mailgw <instance_home>"``
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
241
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
242
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
243 Linux
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
244 -----
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
245
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
246 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
247 ``_weakref``.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
248
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
249 -------------------------------------------------------------------------------
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
250
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
251 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
252
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
253 Next: `Getting Started`_
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 .. _`table of contents`: index.html
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
256 .. _`getting started`: getting_started.html
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
257 .. _`roundup specification`: spec.html
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
258 .. _`customising roundup`: customizing.html
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
259 .. _`upgrading`: upgrading.html
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
260
Roundup Issue Tracker: http://roundup-tracker.org/