1 ===============
2 Getting Started
3 ===============
5 :Version: $Revision: 1.5 $
7 .. contents::
10 The following instructions assume that you have installed roundup. If you
11 haven't, you may still proceed - just run the commands as
12 "``PYTHONPATH=. python roundup/scripts/roundup_admin.py``" for
13 ``roundup-admin`` and
14 "``PYTHONPATH=. python roundup/scripts/roundup_server.py``" for
15 ``roundup-server``.
17 The Instance
18 ------------
20 We'll be referring to the term instance a lot from now on. An instance is a
21 directory in your filesystem that is where all the information about a live
22 issue
23 tracker database is stored. The data that is entered as issues, the users who
24 access the database and the definition of the database itself all reside there:
26 Hyperdatabase
27 This is the lowest component of Roundup and is where all the issues,
28 users, file attachments and messages are stored.
30 Database schema
31 This describes the content of the hyperdatabase - what fields are stored
32 for issues, what user information, etc. Being stored in the instance,
33 this allows it to be customised for a particular application. It also
34 means that changes in the Roundup core code do not affect a running
35 instance.
37 Web Interface
38 The web interface templates are defined in the instance too - and the
39 actual CGI interface class is defined (mostly using base classes in the
40 Roundup core code) so it, like the database, may be customised for each
41 instance in use.
43 Instances are created using the ``roundup-admin`` tool.
45 Command Line Tool
46 -----------------
48 To set up a new instance, run "``roundup-admin install``". You will be
49 asked a few questions:
51 1. Instance home directory
52 2. Schema to use
53 3. Database back-end to use
55 Once you've chosen these, roundup will install the instance for you. It will
56 then indicate that you should configure some more information in the
57 file "``instance_config.py``" in the instance home. It
58 should be edited before roundup is initialised, and may have the following
59 variable declarations:
61 MAILHOST
62 The SMTP mail host that roundup will use to send mail
63 MAIL_DOMAIN
64 The domain name used for email addresses
65 ISSUE_TRACKER_WEB
66 The web address of the issue tracker's web interface
68 The email addresses used by the system by default are:
70 ISSUE_TRACKER_EMAIL: ``issue_tracker@MAIL_DOMAIN``
71 submissions of issues
73 ADMIN_EMAIL: ``roundup-admin@MAIL_DOMAIN``
74 roundup's internal use (problems, etc)
76 You may also alter the default schema - see the `customisation`_ documentation
77 for more info on both configuration variables and schema modifications.
79 Once you're happy (and note that you can change any of this after the instance
80 is initialised too!) you must run "``roundup-admin initialise``".
82 You should also think about whether there is going to be controlled access
83 to the
84 instance on the machine the instance is running on. That is, who can
85 actually make
86 changes to the database using the roundup-admin tool. See the section on
87 Users_and_Access_Control for information on how to secure your instance from the
88 start.
90 E-Mail Interface
91 ----------------
93 Setup 1: As a mail alias pipe process
94 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
96 Set up a mail alias called "issue_tracker" as (include the quote marks):
97 "``|/usr/bin/python /usr/local/bin/roundup-mailgw <instance_home>``"
99 In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh so
100 sendmail will accept the pipe command. In that case, symlink
101 ``/etc/smrsh/roundup-mailgw`` to "``/usr/local/bin/roundup-mailgw``" and change
102 the command to::
104 |roundup-mailgw <instance_home>
106 To test the mail gateway on unix systems, try::
108 echo test |mail -s '[issue] test' issue_tracker@your.domain
111 Setup 2: As a regular cron job using a mailbox source
112 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
114 Set ``roundup-mailgw`` up to run every 10 minutes or so. For example::
116 10 * * * * /usr/local/bin/roundup-mailgw <instance_home> mailbox <mail_spool_file>
118 Where the ``mail_spool_file`` argument is the location of the roundup submission
119 user's mail spool. On most systems, the spool for a user "issue_tracker"
120 will be "``/var/mail/issue_tracker``".
122 Setup 3: As a regular cron job using a POP source
123 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
125 To retrieve from a POP mailbox, use a similar cron entry to the mailbox one::
127 10 * * * * /usr/local/bin/roundup-mailgw <instance_home> pop <pop_spec>
129 where pop_spec is "``username:password@server``" that specifies the roundup
130 submission user's POP account name, password and server.
133 Web Interface
134 -------------
136 This software will work through apache or stand-alone.
138 Stand-alone:
139 1. Edit roundup-server at the top - ``ROUNDUP_INSTANCE_HOMES`` needs to know
140 about your instance. You may also specify the values for
141 ``ROUNDUP_INSTANCE_HOMES`` on the command-line using "name=home" pairs.
143 2. "``roundup-server [-p port] (name=instance_home)*``" (hostname may be "")
145 3. Load up the page "``/<instance name>/index``" where instance name is the name
146 you nominated in ``ROUNDUP_INSTANCE_HOMES``.
148 Apache:
149 1. The CGI script is found in the cgi-bin directory of the roundup
150 distribution.
152 2. Make sure roundup.cgi is executable. Edit it at the top -
153 ``ROUNDUP_INSTANCE_HOMES`` needs to know about your instance.
155 3. Edit your "``/etc/httpd/conf/httpd.conf``" and make sure that the
156 "``/home/httpd/html/roundup/roundup.cgi``" script will be treated as a CGI script.
158 4. Re-start your apache to re-load the config if necessary.
160 5. Load up the page "``/roundup/roundup.cgi/index/``" where instance name is the
161 name you nominated in ``ROUNDUP_INSTANCE_HOMES``.
163 6. To use the CGI script unchanged, which allows much easier updates, add
164 these directives to your "httpd.conf"::
166 SetEnv ROUNDUP_LOG "/var/log/roundup.log"
167 SetEnv ROUNDUP_INSTANCE_HOMES "Default=/usr/local/share/roundup/instances/Default"
168 SetEnv ROUNDUP_DEBUG "0"
170 7. On Windows, write a batch file "roundup.bat" similar to the one below and
171 place it into your cgi-bin directory::
173 @echo off
174 set ROUNDUP_LOG=c:\Python21\share\roundup\cgi.log
175 set ROUNDUP_INSTANCE_HOMES=Default=c:\Python21\share\roundup\instances\Default;
176 set ROUNDUP_DEBUG=0
177 c:\Python21\python.exe c:\Python21\share\roundup\cgi-bin\roundup.cgi
180 Users
181 -----
183 Users and permissions
184 ~~~~~~~~~~~~~~~~~~~~~
186 By default, roundup automatically creates one user when the instance database is
187 initialised (using roundup-admin init). The user is "admin" and the password is
188 the one you supply at that time.
190 If users attempt to use roundup in any manner and are not identified to roundup,
191 they will be using the database in a read-only mode. That is, if roundup doesn't
192 know who they are, they can't change anything. This has the following
193 repurcussions:
195 Command-line interface
196 The data modification commands (create, init, retire, set) are performed
197 as the "admin" user. It is therefore important that the database be
198 protected by the filesystem if protection is required. On a Unix system,
199 the easiest and most flexible method of doing so is:
201 1. Add a new user and group to your system (e.g. "issue_tracker")
203 2. When creating a new instance home, use the following commands
204 (substituting instance_home for the directory you want to use)::
206 mkdir instance_home
207 chown issue_tracker:issue_tracker instance_home
208 chmod g+rwxs instance_home
209 roundup-admin -i instance_home init
211 3. Now, edit the /etc/group line for the issue_tracker group so it
212 includes the unix logins of all the users who are going to
213 administer your roundup instance. If you're running the web or mail
214 gateways, then be sure to include those users in the group too (on
215 some Linux systems, these users are "www" or "apache" and "mail".)
217 E-Mail interface
218 Users are identified by e-mail address - a new user entry will be created
219 for any e-mail address that is not recognised, so users are always
220 identified by roundup.
222 Web interface
223 Unidentified users have read-only access. If the users database has an
224 entry with the username "anonymous", then unidentified users are
225 automatically logged in as that user. This gives them write access.
227 **anonymous access and the ANONYMOUS_* configurations.**
230 Adding users
231 ~~~~~~~~~~~~
233 To add users, use one of the following interfaces:
235 1. On the web, access the URL .../<instance name>/newuser to bring up a form
236 which may be used to add a new user.
238 2. On the command-line, use::
240 roundup-admin -i <instance home> create user username=bozo password=bozo
241 address=richard@clown.org
243 Supply the admin username and password. roundup-admin will print the id
244 of the new user.
246 3. Any e-mail sent to roundup from an address that doesn't match an existing
247 user in the database will result in a new user entry being created for
248 that user.
251 Issues
252 ------
254 To add issues, use one of the following interfaces:
256 1. On the web, access the URL .../<instance name>/newissue to bring up a
257 form which may be used to add a new issue.
259 2. On the command-line, use::
261 roundup-admin -i <instance home> create issue title="test issue"
263 Supply the admin username and password. roundup-admin will print the id
264 of the new issue.
266 3. Any e-mail sent to roundup with the subject line containing [issue] will
267 automatically created a new issue in the database using the contents of
268 the e-mail.
270 -----------------
272 Back to `Table of Contents`_
274 Next: `User Guide`_
276 .. _`table of contents`: index.html
277 .. _`user guide`: user_guide.html
278 .. _`customisation`: customizing.html