cef6f00f50ae12eb23f7b4e7aff3c3e0f9f44b9b
1 ===============
2 Getting Started
3 ===============
5 :Version: $Revision: 1.3 $
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 initiliase a new instance, run "``roundup-admin init``". You will be asked a
49 series of questions:
51 1. Instance home directory
52 2. Schema to use
53 3. Database back-end to use
54 4. Administration user "admin" password.
56 You should also think about whether there is going to be controlled access
57 to the
58 instance on the machine the instance is running on. That is, who can
59 actually make
60 changes to the database using the roundup-admin tool. See the section on
61 Users_and_Access_Control for information on how to secure your instance from the
62 start.
64 Roundup is configurable using an ``instance_config.py`` file in the instance
65 home. It
66 should be edited before roundup is used, and may have the following variable
67 declarations:
69 MAILHOST
70 The SMTP mail host that roundup will use to send mail
71 MAIL_DOMAIN
72 The domain name used for email addresses
73 ISSUE_TRACKER_WEB
74 The web address of the issue tracker's web interface
76 The email addresses used by the system by default are:
78 ISSUE_TRACKER_EMAIL: ``issue_tracker@MAIL_DOMAIN``
79 submissions of issues
81 ADMIN_EMAIL: ``roundup-admin@MAIL_DOMAIN``
82 roundup's internal use (problems, etc)
84 E-Mail Interface
85 ----------------
87 Setup 1: As a mail alias pipe process
88 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
90 Set up a mail alias called "issue_tracker" as (include the quote marks):
91 "``|/usr/bin/python /usr/local/bin/roundup-mailgw <instance_home>``"
93 In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh so
94 sendmail will accept the pipe command. In that case, symlink
95 ``/etc/smrsh/roundup-mailgw`` to "``/usr/local/bin/roundup-mailgw``" and change
96 the command to::
98 |roundup-mailgw <instance_home>
100 To test the mail gateway on unix systems, try::
102 echo test |mail -s '[issue] test' issue_tracker@your.domain
105 Setup 2: As a regular cron job using a mailbox source
106 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
108 Set ``roundup-mailgw`` up to run every 10 minutes or so. For example::
110 10 * * * * /usr/local/bin/roundup-mailgw <instance_home> mailbox <mail_spool_file>
112 Where the ``mail_spool_file`` argument is the location of the roundup submission
113 user's mail spool. On most systems, the spool for a user "issue_tracker"
114 will be "``/var/mail/issue_tracker``".
116 Setup 3: As a regular cron job using a POP source
117 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
119 To retrieve from a POP mailbox, use a similar cron entry to the mailbox one::
121 10 * * * * /usr/local/bin/roundup-mailgw <instance_home> pop <pop_spec>
123 where pop_spec is "``username:password@server``" that specifies the roundup
124 submission user's POP account name, password and server.
127 Web Interface
128 -------------
130 This software will work through apache or stand-alone.
132 Stand-alone:
133 1. Edit roundup-server at the top - ``ROUNDUP_INSTANCE_HOMES`` needs to know
134 about your instance. You may also specify the values for
135 ``ROUNDUP_INSTANCE_HOMES`` on the command-line using "name=home" pairs.
137 2. "``roundup-server [-p port] (name=instance_home)*``" (hostname may be "")
139 3. Load up the page "``/<instance name>/index``" where instance name is the name
140 you nominated in ``ROUNDUP_INSTANCE_HOMES``.
142 Apache:
143 1. The CGI script is found in the cgi-bin directory of the roundup
144 distribution.
146 2. Make sure roundup.cgi is executable. Edit it at the top -
147 ``ROUNDUP_INSTANCE_HOMES`` needs to know about your instance.
149 3. Edit your "``/etc/httpd/conf/httpd.conf``" and make sure that the
150 "``/home/httpd/html/roundup/roundup.cgi``" script will be treated as a CGI script.
152 4. Re-start your apache to re-load the config if necessary.
154 5. Load up the page "``/roundup/roundup.cgi/index/``" where instance name is the
155 name you nominated in ``ROUNDUP_INSTANCE_HOMES``.
157 6. To use the CGI script unchanged, which allows much easier updates, add
158 these directives to your "httpd.conf"::
160 SetEnv ROUNDUP_LOG "/var/log/roundup.log"
161 SetEnv ROUNDUP_INSTANCE_HOMES "Default=/usr/local/share/roundup/instances/Default"
162 SetEnv ROUNDUP_DEBUG "0"
164 7. On Windows, write a batch file "roundup.bat" similar to the one below and
165 place it into your cgi-bin directory::
167 @echo off
168 set ROUNDUP_LOG=c:\Python21\share\roundup\cgi.log
169 set ROUNDUP_INSTANCE_HOMES=Default=c:\Python21\share\roundup\instances\Default;
170 set ROUNDUP_DEBUG=0
171 c:\Python21\python.exe c:\Python21\share\roundup\cgi-bin\roundup.cgi
174 Users
175 -----
177 Users and permissions
178 ~~~~~~~~~~~~~~~~~~~~~
180 By default, roundup automatically creates one user when the instance database is
181 initialised (using roundup-admin init). The user is "admin" and the password is
182 the one you supply at that time.
184 If users attempt to use roundup in any manner and are not identified to roundup,
185 they will be using the database in a read-only mode. That is, if roundup doesn't
186 know who they are, they can't change anything. This has the following
187 repurcussions:
189 Command-line interface
190 The data modification commands (create, init, retire, set) are performed
191 as the "admin" user. It is therefore important that the database be
192 protected by the filesystem if protection is required. On a Unix system,
193 the easiest and most flexible method of doing so is:
195 1. Add a new user and group to your system (e.g. "issue_tracker")
197 2. When creating a new instance home, use the following commands
198 (substituting instance_home for the directory you want to use)::
200 mkdir instance_home
201 chown issue_tracker:issue_tracker instance_home
202 chmod g+rwxs instance_home
203 roundup-admin -i instance_home init
205 3. Now, edit the /etc/group line for the issue_tracker group so it
206 includes the unix logins of all the users who are going to
207 administer your roundup instance. If you're running the web or mail
208 gateways, then be sure to include those users in the group too (on
209 some Linux systems, these users are "www" or "apache" and "mail".)
211 E-Mail interface
212 Users are identified by e-mail address - a new user entry will be created
213 for any e-mail address that is not recognised, so users are always
214 identified by roundup.
216 Web interface
217 Unidentified users have read-only access. If the users database has an
218 entry with the username "anonymous", then unidentified users are
219 automatically logged in as that user. This gives them write access.
221 **anonymous access and the ANONYMOUS_* configurations.**
224 Adding users
225 ~~~~~~~~~~~~
227 To add users, use one of the following interfaces:
229 1. On the web, access the URL .../<instance name>/newuser to bring up a form
230 which may be used to add a new user.
232 2. On the command-line, use::
234 roundup-admin -i <instance home> create user username=bozo password=bozo
235 address=richard@clown.org
237 Supply the admin username and password. roundup-admin will print the id
238 of the new user.
240 3. Any e-mail sent to roundup from an address that doesn't match an existing
241 user in the database will result in a new user entry being created for
242 that user.
245 Issues
246 ------
248 To add issues, use one of the following interfaces:
250 1. On the web, access the URL .../<instance name>/newissue to bring up a
251 form which may be used to add a new issue.
253 2. On the command-line, use::
255 roundup-admin -i <instance home> create issue title="test issue"
257 Supply the admin username and password. roundup-admin will print the id
258 of the new issue.
260 3. Any e-mail sent to roundup with the subject line containing [issue] will
261 automatically created a new issue in the database using the contents of
262 the e-mail.
264 -----------------
266 Back to `Table of Contents`_
268 Next: `User Guide`_
270 .. _`table of contents`: index.html
271 .. _`user guide`: user_guide.html