Mercurial > p > roundup > code

comparison doc/installation.stx @ 653:1dcbee29faa7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
More work on the documentation - rolled in the work done by Jeff Blaine. Use build_html.py *.stx to build the HTML. We'll move that into the setup script when someone figures how to :)
author Richard Jones <richard@users.sourceforge.net>
date Fri, 08 Mar 2002 23:41:46 +0000
parents 7875cd9af1cb
children 35cdc70e6a96
comparison
equal deleted inserted replaced
652:66b324f895d1 653:1dcbee29faa7
1 *Roundup (0.4.1): An Issue-Tracking System for Knowledge Workers* 1 *Roundup (0.4.1): An Issue-Tracking System for Knowledge Workers*
2 2
3 `Table of contents`_ 3 `Table of contents`_
4 4
5 1. Prerequisites_ 5 - Overview_
6 2. `Getting Roundup`_ 6 - Prerequisites_
7 3. `Installing Roundup`_
8 7
8 - `Testing your Python`_
9
10 - `Getting Roundup`_
11 - `Installation`_
12 - `Further Reading`_
13 - `Platform-Specific Notes`_
14
15 Overview
16 ========
17
18 TODO
9 19
10 Prerequisites 20 Prerequisites
11 ------------- 21 =============
12 22
13 Python 2.1.1 is required for the correct operation of roundup. 23 Python 2.1.1 or newer with a functioning anydbm or bsddb module.
14 24
15 Download the latest version from http://www.python.org/. 25 Download the latest version from http://www.python.org/.
16 26
17 27
28 Testing your Python
29 -------------------
30
31 Run ``"python -c 'import test;test.go()'"`` and make sure there
32 are no errors. If there are errors, please let us know!
33
34
18 Getting Roundup 35 Getting Roundup
19 --------------- 36 ===============
20 37
21 Download the latest version from http://roundup.sf.net/. 38 Download the latest version from http://roundup.sf.net/.
22 39
23 Installing Roundup
24 ------------------
25 40
26 Run: 41 Installation
42 ============
27 43
28 - "``python setup.py install``" 44 Set aside 15-30 minutes.
29 - If you would prefer the scripts installed in somewhere other than
30 "``/usr/local/bin``", add "``--install-scripts=<dir>``" to the
31 command::
32 45
33 python setup.py install --install-scripts=<dir> 46 Broken out separately, there are several conceptual pieces to a
47 Roundup installation:
34 48
35 - This command gives all the options available for 49 Roundup support code
36 installation:: 50 Installed into your Python install's lib directory
37 51
38 python setup.py install --help 52 Roundup scripts
53 These include the email gateway, the roundup
54 HTTP server, the roundup administration command-line interface, etc.
39 55
56 Roundup instances
57 Instances consist of core support files, issues
58 (be they bug reports or otherwise), instance configuration file(s),
59 etc. Roundup instances also adhere to a specific "Template" which
60 defines the fields usable/assignable on a per-issue basis. A
61 description of the provided templates can be found under the
62 'TODO' section.
63
64 1. To install the Roundup support code into your Python tree and
65 Roundup scripts into /usr/local/bin::
66
67 python setup.py install
68
69 If you would like to place the Roundup scripts in a directory other
70 than ``/usr/local/bin``, use the ``--install-scripts`` option as follows,
71 replacing ``/opt/roundup/bin`` with the location where you would like
72 the scripts to reside::
73
74 python setup.py install --install-scripts=/opt/roundup/bin
75
76 2. To create a Roundup instance (necessary to do before you can
77 use the software in any real fashion):
78
79 a. (Optional) If you intend to keep your roundup instances
80 under one top level directory which does not exist yet,
81 you should create that directory now. Example:
82
83 mkdir /opt/roundup/instances
84
85 b. Either add the Roundup script location to your ``PATH``
86 environment variable or specify the full path to
87 the command in the next step.
88
89 c. ``roundup-admin init``
90
91 You will be asked a series of questions. A description of
92 the Roundup-provided templates can be found under TODO::
93
94 Enter instance home: /opt/roundup/instances/support
95 Templates: classic, extended
96 Select template [classic]: classic
97 Back ends: anydbm, bsddb
98 Select backend [anydbm]: anydbm
99 Admin Password:
100 Confirm:
101
102 3. Each instance ideally should have its own UNIX group, so create
103 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
104 you're using NIS). To continue with my examples so far, I would
105 create the UNIX group 'support', although the name of the UNIX
106 group does not have to be the same as the instance name. To this
107 'support' group I then add all of the UNIX usernames who will be
108 working with this Roundup instance. In addition to 'real' users,
109 the Roundup email gateway will need to have permissions to this
110 area as well, so add the user your mail service runs as to the
111 group. The UNIX group might then look like::
112
113 support:*:1002:jblaine,samh,geezer,mail
114
115 If you intend to use the web interface (as most people do), you
116 should also add the username your web server runs as to the group.
117 My group now looks like this::
118
119 support:*:1002:jblaine,samh,geezer,mail,apache
120
121 4. Configure your new instance by editing the file ``instance_config.py``
122 located in the instance home you specified in step 2c above. This
123 file is Python code and must adhere to Python syntax rules, but
124 don't be daunted if you do not know Python - it should look pretty
125 straightfoward if you carefully read the comments in the file.
126
127 5. There are two supported ways to get emailed issues into the
128 Roundup instance. You should pick ONE of the following, both
129 of which will continue my example setup from above:
130
131 a. Set up a mail alias called "support" as::
132
133 "|/opt/roundup/bin/roundup-mailgw /opt/roundup/instances/support"
134
135 If you use Sendmail's ``smrsh`` mechanism, please read the notes
136 under 'Platform-Specific Notes'
137
138 b. OR... Configure roundup-mailgw to run every 10 minutes or
139 so via ``cron``. My cron job would be (these 2 lines all on one
140 line)::
141
142 10 * * * * /opt/roundup/bin/roundup-mailgw
143 /opt/roundup/instances/support /var/mail/support
144
145 6. TODO (mention perms)
146
147 7. Test the email gateway. Under most flavors of UNIX, this
148 can be done by::
149
150 echo test | mail -s '[issue] test' support@YOUR_DOMAIN_HERE
151
152 TODO (finish)
153
154
155 Further Reading
156 ===============
157
158 If you intend to use Roundup with anything other than the defualt
159 templates, if you would like to hack on Roundup, or if you would
160 like implementation details, you should read 'TODO'
161
162 Platform-Specific Notes
163 =======================
164
165 Sendmail smrsh
166 --------------
167
168 If you use Sendmail's ``smrsh`` mechanism, you will need to tell
169 smrsh that roundup-mailgw is a valid/trusted mail handler
170 before it will work.
171
172 This is usually done via the following 2 steps:
173
174 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
175 which points to the full path of your actual ``roundup-mailgw``
176 script.
177
178 2. change your alias to ``"|roundup-mailgw <instance_home>"``
179
180
181 Linux
182 -----
183
184 Python 2.1.1 as shipped with SuSE7.3 might be missing module
185 ``_weakref``.
186
187 -------------------------------------------------------------------------------
40 188
41 Next: `Getting Started`_ 189 Next: `Getting Started`_
42 190
43 .. _`table of contents`: index.html 191 .. _`table of contents`: index.html
44 .. _`getting started`: getting_started.html 192 .. _`getting started`: getting_started.html
45 193
46 $Id: installation.stx,v 1.1 2002-02-21 06:22:00 richard Exp $ 194 $Id: installation.stx,v 1.2 2002-03-08 23:41:46 richard Exp $
Roundup Issue Tracker: http://roundup-tracker.org/