Mercurial > p > roundup > code

comparison doc/index.html @ 251:2f4123c715f1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Started working on some _real_ documentation!
author Richard Jones <richard@users.sourceforge.net>
date Sat, 29 Sep 2001 13:09:32 +0000
parents
children 5973f1d80ace
comparison
equal deleted inserted replaced
250:1d428068485c 251:2f4123c715f1
1 <html><head>
2 <title>Roundup: an Issue-Tracking System for Knowledge Workers</title>
3 </head><body>
4
5 <h1 align=center>Roundup</h1>
6 <h3 align=center>An Issue-Tracking System for Knowledge Workers</h3>
7
8 <h2>Contents</h2>
9
10 <ul>
11 <li><a href="overview.html">Overview</a> (Initial submission to SC Track)
12 <li><a href="#installation">Installation</a>
13 <ul>
14 <li><a href="#requires">Prerequisites</a>
15 <li><a href="#getting">Getting Roundup</a>
16 <li><a href="#installing">Installing Roundup</a>
17 </ul>
18 <li><a href="#starting">Getting Started</a>
19 <ul>
20 <li><a href="#instance">The Instance</a>
21 <li><a href="#startcmd">Command Line Tool</a>
22 <li><a href="#startweb">E-Mail Interface</a>
23 <li><a href="#startweb">Web Interface</a>
24 <li><a href="#users">Users</a>
25 <li><a href="#issues">Issues</a>
26 </ul>
27 <li><a href="#admin">Administration</a>
28 <ul>
29 <li><a href="#cmd">Command Line Tool</a>
30 <li><a href="#web">Web Interface</a>
31 <li><a href="#mail">E-Mail Gateway</a>
32 </ul>
33 <li><a href="spec.html">Roundup's Design Document</a> ("Implementation Guide")
34 <li><a href="#ack">Acknowledgements</a>
35 </ul>
36
37 <p><hr>
38 <h2><a name="installation">Installation</a></h2>
39
40
41 <h3><a name="requires">Prerequisites</a></h3>
42
43 <dl>
44 <dt>Either:
45 <dd>Python 2.0 with pydoc installed. See http://www.lfw.org/ for pydoc.
46 <dt>or
47 <dd>Python 2.1 or later
48 </dl>
49
50 Download the latest version from
51 <a href="http://www.python.org/">http://www.python.org/</a>.
52
53
54
55 <h3><a name="getting">Getting Roundup</a></h3>
56
57 Download the latest version from
58 <a href="http://roundup.sf.net/">http://roundup.sf.net/</a>.
59
60
61 <h3><a name="installing">Installing Roundup</a></h3>
62
63 <ol>
64 <li>Run:
65 <br><tt>python setup.py install</tt>
66 <li>If you would prefer the scripts installed in somewhere other than
67 <tt>/usr/local/bin</tt>, add <tt>"--install-scripts=&lt;dir&gt;"</tt>
68 to the command:
69 <br><tt>python setup.py install --install-scripts=&lt;dir&gt;</tt>
70 <li>The command:
71 <br><tt>python setup.py install --help</tt>
72 <br>gives all the options available for installation.
73 </ol>
74
75
76 <p><hr>
77 <h2><a name="starting">Getting Started</a></h2>
78
79 The following instructions assume that you have installed roundup. If you
80 haven't, you may still proceed - just preface all commands with "./"
81 ie. "./roundup-admin init".
82
83
84 <h3><a name="instance">The Instance</a></h3>
85
86 We'll be referring to the term "instance" a lot from now on. An instance is
87 a directory in your filesystem that is where all the information about a
88 live issue tracker database is stored. The data that is entered as issues,
89 the users who access the database and the definition of the database itself
90 all reside there:
91 <ol>
92 <li><strong>Hyperdatabase</strong>
93 <br>This is the lowest component of Roundup and is where all the
94 issues, users, file attachments and messages are stored.
95 <li><strong>Database schema</strong>
96 <br>This describes the content of the hyperdatabase - what fields are
97 stored for issues, what user information, etc. Being stored in the
98 instance, this allows it to be customised for a particular application.
99 It also means that changes in the Roundup core code do not affect a
100 running instance.
101 <li><strong>Web Interface</strong>
102 <br>The web interface templates are defined in the instance too - and
103 the actual CGI interface class is defined (mostly using base classes in
104 the Roundup core code) so it, like the database, may be customised for
105 each instance in use.
106 </ol>
107
108 Instances are created using the <tt>roundup-admin</tt> tool.
109
110 <h3><a name="startcmd">Command Line Tool</a></h3>
111
112 To initiliase a new instance, run <tt>roundup-admin init</tt>. You will be
113 asked a series of questions:
114
115 <ol>
116 <li>Instance home directory
117 <li>Schema to use
118 <li>Database back-end to use
119 <li>Administration user "admin" password.
120 </ol>
121
122 Roundup is configurable using a localconfig.py file in the instance home.
123 It may have the following variable declarations:
124
125 <ol>
126 <li>MAILHOST
127 <br>The SMTP mail host that roundup will use to send mail
128 <li>MAIL_DOMAIN
129 <br>The domain name used for email addresses
130 </ol>
131
132 Any further configuration should be possible by editing the instance home's
133 __init__.py directly.
134 <p>
135 The email addresses used by the system by default are:
136
137 <ol>
138 <li>issue_tracker@MAIL_DOMAIN
139 <br>submissions of issues
140 <li>roundup-admin@MAIL_DOMAIN
141 <br>roundup's internal use (problems, etc)
142 </ol>
143
144 <em>Note:</em>
145 We run the instance as group "issue_tracker" and add the mail and web user
146 ("mail" and "apache" on our RedHat 7.1 system) to that group, as well as
147 any admin people.
148
149
150 <h3><a name="startweb">E-Mail Interface</a></h3>
151 Set up a mail alias called "issue_tracker" as:
152 <blockquote>
153 <tt>|/usr/bin/python /usr/local/bin/roundup-mailgw
154 &lt;instance_home&gt;</tt>
155 </blockquote>
156
157 In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh
158 so sendmail will accept the pipe command. In that case, symlink
159 /etc/smrsh/roundup-mailgw to /usr/local/bin/roundup-mailgw and change the
160 command to:
161 <blockquote>
162 <tt>|roundup-mailgw &lt;instance_home&gt;</tt>
163 </blockquote>
164
165 To test the mail gateway on unix systems, try:
166
167 <blockquote>
168 <tt>echo test |mail -s '[issue] test' issue_tracker@your.domain</tt>
169 </blockquote>
170
171
172
173 <h3><a name="startweb">Web Interface</a></h3>
174 This software will work through apache or stand-alone.
175 <p>
176 <strong>Stand-alone:</strong>
177 <ol>
178 <li>Edit roundup-server at the top - ROUNDUP_INSTANCE_HOMES needs to know
179 about your instance. *** command-line option
180 <li><tt>roundup-server [hostname port]</tt> (hostname may be "")
181 <li>Load up the page <tt>/&lt;instance name&gt;/index</tt> where
182 instance name is the
183 name you nominated in <tt>ROUNDUP_INSTANCE_HOMES</tt>.
184 *** command-line option
185 </ol>
186
187 <strong>Apache:</strong>
188 <ol>
189 <li>Make sure roundup.cgi is executable. Edit it at the top -
190 ROUNDUP_INSTANCE_HOMES needs to know about your instance.
191 <li>Edit your <tt>/etc/httpd/conf/httpd.conf</tt> and make sure that the
192 <tt>/home/httpd/html/roundup/roundup.cgi</tt> script will be treated as a CGI
193 script.
194 <li>Add the following to your <tt>/etc/httpd/conf/httpd.conf</tt>:
195 <pre>
196 ------8<------- snip here ------8<-------
197 RewriteEngine on
198 RewriteCond %{HTTP:Authorization} ^(.*)
199 RewriteRule ^/roundup/roundup.cgi(.*) /home/httpd/html/roundup/roundup.cgi$1 [e=HTTP_CGI_AUTHORIZATION:%1,t=application/x-httpd-cgi,l]
200 ------8<------- snip here ------8<-------
201 </pre>
202 note: the RewriteRule must be on one line - no breaks
203 <li>Re-start your apache to re-load the config
204 <li>Load up the page <tt>/roundup/roundup.cgi/&lt;instance name&gt;/index</tt> where
205 instance name is the name you nominated in ROUNDUP_INSTANCE_HOMES.
206 </ol>
207
208
209 <h3><a name="users">Users</a></h3>
210 To add users, use one of the following interfaces:
211
212 <ol>
213 <li>On the web, access the URL <tt>.../&lt;instance name&gt;/newuser</tt>
214 to bring up a form which may be used to add a new user.
215 <li>On the command-line, use:
216 <br><tt>roundup-admin -i &lt;instance home&gt; create user
217 username=bozo password=bozo address=richard@clown.org</tt>
218 <br>Supply the admin username and password. roundup-admin will print the
219 id of the new user.
220 <li>Any e-mail sent to roundup from an address that doesn't match an
221 existing user in the database will result in a new user entry being
222 created for that user.
223 </ol>
224
225
226
227 <h3><a name="issues">Issues</a></h3>
228 To add issues, use one of the following interfaces:
229
230 <ol>
231 <li>On the web, access the URL <tt>.../&lt;instance name&gt;/newissue</tt>
232 to bring up a form which may be used to add a new issue.
233 <li>On the command-line, use:
234 <br><tt>roundup-admin -i &lt;instance home&gt; create issue
235 title="test issue"</tt>
236 <br>Supply the admin username and password. roundup-admin will print the
237 id of the new issue.
238 <li>Any e-mail sent to roundup with the subject line containing [issue]
239 will automatically created a new issue in the database using the
240 contents of the e-mail.
241 </ol>
242
243 <p><hr>
244 <h2><a name="ack">Acknowledgements</a></h2>
245
246 Go Ping, you rock! Also, go Bizar Software for letting me implement this
247 system on their time.
248
249 </body></html>
Roundup Issue Tracker: http://roundup-tracker.org/