Skip to content

Commit b9f8358

Browse files
author
Richard Jones
committed
Started working on some _real_ documentation!
1 parent 01b8c38 commit b9f8358

File tree

1 file changed

+249
-0
lines changed

1 file changed

+249
-0
lines changed

‎doc/index.html‎

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
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' [email protected]</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 [email protected]</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>

0 commit comments

Comments
 (0)