1 Getting Started
2 ===============
4 The following instructions assume that you have installed roundup. If you
5 haven't, you may still proceed - just run the commands as
6 "``PYTHONPATH=. python roundup/scripts/roundup_admin.py``" for
7 ``roundup-admin`` and
8 "``PYTHONPATH=. python roundup/scripts/roundup_server.py``" for
9 ``roundup-server``.
11 The Instance
12 ------------
14 We'll be referring to the term instance a lot from now on. An instance is a
15 directory in your filesystem that is where all the information about a live
16 issue
17 tracker database is stored. The data that is entered as issues, the users who
18 access the database and the definition of the database itself all reside there:
20 Hyperdatabase
21 This is the lowest component of Roundup and is where all the issues,
22 users, file attachments and messages are stored.
24 Database schema
25 This describes the content of the hyperdatabase - what fields are stored
26 for issues, what user information, etc. Being stored in the instance,
27 this allows it to be customised for a particular application. It also
28 means that changes in the Roundup core code do not affect a running
29 instance.
31 Web Interface
32 The web interface templates are defined in the instance too - and the
33 actual CGI interface class is defined (mostly using base classes in the
34 Roundup core code) so it, like the database, may be customised for each
35 instance in use.
37 Instances are created using the ``roundup-admin`` tool.
39 Command Line Tool
40 -----------------
42 To initiliase a new instance, run "``roundup-admin init``". You will be asked a
43 series of questions:
45 1. Instance home directory
46 2. Schema to use
47 3. Database back-end to use
48 4. Administration user "admin" password.
50 You should also think about whether there is going to be controlled access
51 to the
52 instance on the machine the instance is running on. That is, who can
53 actually make
54 changes to the database using the roundup-admin tool. See the section on
55 Users_and_Access_Control for information on how to secure your instance from the
56 start.
58 Roundup is configurable using an ``instance_config.py`` file in the instance
59 home. It
60 should be edited before roundup is used, and may have the following variable
61 declarations:
63 MAILHOST
64 The SMTP mail host that roundup will use to send mail
65 MAIL_DOMAIN
66 The domain name used for email addresses
67 ISSUE_TRACKER_WEB
68 The web address of the issue tracker's web interface
70 The email addresses used by the system by default are:
72 ISSUE_TRACKER_EMAIL: ``issue_tracker@MAIL_DOMAIN``
73 submissions of issues
75 ADMIN_EMAIL: ``roundup-admin@MAIL_DOMAIN``
76 roundup's internal use (problems, etc)
78 E-Mail Interface
79 ----------------
81 Setup 1: As a mail alias pipe process
82 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
84 Set up a mail alias called "issue_tracker" as (include the quote marks):
85 "``|/usr/bin/python /usr/local/bin/roundup-mailgw <instance_home>``"
87 In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh so
88 sendmail will accept the pipe command. In that case, symlink
89 ``/etc/smrsh/roundup-mailgw`` to "``/usr/local/bin/roundup-mailgw``" and change
90 the command to::
92 |roundup-mailgw <instance_home>
94 To test the mail gateway on unix systems, try::
96 echo test |mail -s '[issue] test' issue_tracker@your.domain
99 Setup 2: As a regular cron job using a mailbox source
100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
102 Set ``roundup-mailgw`` up to run every 10 minutes or so. For example::
104 10 * * * * /usr/local/bin/roundup-mailgw <instance_home> mailbox <mail_spool_file>
106 Where the ``mail_spool_file`` argument is the location of the roundup submission
107 user's mail spool. On most systems, the spool for a user "issue_tracker"
108 will be "``/var/mail/issue_tracker``".
110 Setup 3: As a regular cron job using a POP source
111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
113 To retrieve from a POP mailbox, use a similar cron entry to the mailbox one::
115 10 * * * * /usr/local/bin/roundup-mailgw <instance_home> pop <pop_spec>
117 where pop_spec is "``username:password@server``" that specifies the roundup
118 submission user's POP account name, password and server.
121 Web Interface
122 -------------
124 This software will work through apache or stand-alone.
126 Stand-alone:
127 1. Edit roundup-server at the top - ``ROUNDUP_INSTANCE_HOMES`` needs to know
128 about your instance. You may also specify the values for
129 ``ROUNDUP_INSTANCE_HOMES`` on the command-line using "name=home" pairs.
131 2. "``roundup-server [-p port] (name=instance_home)*``" (hostname may be "")
133 3. Load up the page "``/<instance name>/index``" where instance name is the name
134 you nominated in ``ROUNDUP_INSTANCE_HOMES``.
136 Apache:
137 1. The CGI script is found in the cgi-bin directory of the roundup
138 distribution.
140 2. Make sure roundup.cgi is executable. Edit it at the top -
141 ``ROUNDUP_INSTANCE_HOMES`` needs to know about your instance.
143 3. Edit your "``/etc/httpd/conf/httpd.conf``" and make sure that the
144 "``/home/httpd/html/roundup/roundup.cgi``" script will be treated as a CGI script.
146 4. Re-start your apache to re-load the config if necessary.
148 5. Load up the page "``/roundup/roundup.cgi/index/``" where instance name is the
149 name you nominated in ``ROUNDUP_INSTANCE_HOMES``.
151 6. To use the CGI script unchanged, which allows much easier updates, add
152 these directives to your "httpd.conf"::
154 SetEnv ROUNDUP_LOG "/var/log/roundup.log"
155 SetEnv ROUNDUP_INSTANCE_HOMES "Default=/usr/local/share/roundup/instances/Default"
156 SetEnv ROUNDUP_DEBUG "0"
158 7. On Windows, write a batch file "roundup.bat" similar to the one below and
159 place it into your cgi-bin directory::
161 @echo off
162 set ROUNDUP_LOG=c:\Python21\share\roundup\cgi.log
163 set ROUNDUP_INSTANCE_HOMES=Default=c:\Python21\share\roundup\instances\Default;
164 set ROUNDUP_DEBUG=0
165 c:\Python21\python.exe c:\Python21\share\roundup\cgi-bin\roundup.cgi
168 Users
169 -----
171 Users and permissions
172 ~~~~~~~~~~~~~~~~~~~~~
174 By default, roundup automatically creates one user when the instance database is
175 initialised (using roundup-admin init). The user is "admin" and the password is
176 the one you supply at that time.
178 If users attempt to use roundup in any manner and are not identified to roundup,
179 they will be using the database in a read-only mode. That is, if roundup doesn't
180 know who they are, they can't change anything. This has the following
181 repurcussions:
183 Command-line interface
184 The data modification commands (create, init, retire, set) are performed
185 as the "admin" user. It is therefore important that the database be
186 protected by the filesystem if protection is required. On a Unix system,
187 the easiest and most flexible method of doing so is:
189 1. Add a new user and group to your system (e.g. "issue_tracker")
191 2. When creating a new instance home, use the following commands
192 (substituting instance_home for the directory you want to use)::
194 mkdir instance_home
195 chown issue_tracker:issue_tracker instance_home
196 chmod g+rwxs instance_home
197 roundup-admin -i instance_home init
199 3. Now, edit the /etc/group line for the issue_tracker group so it
200 includes the unix logins of all the users who are going to
201 administer your roundup instance. If you're running the web or mail
202 gateways, then be sure to include those users in the group too (on
203 some Linux systems, these users are "www" or "apache" and "mail".)
205 E-Mail interface
206 Users are identified by e-mail address - a new user entry will be created
207 for any e-mail address that is not recognised, so users are always
208 identified by roundup.
210 Web interface
211 Unidentified users have read-only access. If the users database has an
212 entry with the username "anonymous", then unidentified users are
213 automatically logged in as that user. This gives them write access.
215 **anonymous access and the ANONYMOUS_* configurations.**
218 Adding users
219 ~~~~~~~~~~~~
221 To add users, use one of the following interfaces:
223 1. On the web, access the URL .../<instance name>/newuser to bring up a form
224 which may be used to add a new user.
226 2. On the command-line, use::
228 roundup-admin -i <instance home> create user username=bozo password=bozo
229 address=richard@clown.org
231 Supply the admin username and password. roundup-admin will print the id
232 of the new user.
234 3. Any e-mail sent to roundup from an address that doesn't match an existing
235 user in the database will result in a new user entry being created for
236 that user.
239 Issues
240 ------
242 To add issues, use one of the following interfaces:
244 1. On the web, access the URL .../<instance name>/newissue to bring up a
245 form which may be used to add a new issue.
247 2. On the command-line, use::
249 roundup-admin -i <instance home> create issue title="test issue"
251 Supply the admin username and password. roundup-admin will print the id
252 of the new issue.
254 3. Any e-mail sent to roundup with the subject line containing [issue] will
255 automatically created a new issue in the database using the contents of
256 the e-mail.