Mercurial > p > roundup > code

annotate doc/getting_started.txt @ 1194:d76b3f8d7bc4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
make import set the id counter to maxid+1
author Richard Jones <richard@users.sourceforge.net>
date Tue, 24 Sep 2002 01:36:04 +0000
parents fa7df238e2d4
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
688
b38f4f95bffd More doc tweaks
Richard Jones <richard@users.sourceforge.net>
parents: 686
diff changeset
1 ===============
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2 Getting Started
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3 ===============
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
4
1096
fa7df238e2d4 More cleaning up of configuration, and the "instance" -> "tracker" renaming.
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
5 :Version: $Revision: 1.7 $
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
6
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
7 .. contents::
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
8
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
9
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
10 The following instructions assume that you have installed roundup. If you
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
11 haven't, you may still proceed - just run the commands as
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
12 "``PYTHONPATH=. python roundup/scripts/roundup_admin.py``" for
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
13 ``roundup-admin`` and
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
14 "``PYTHONPATH=. python roundup/scripts/roundup_server.py``" for
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
15 ``roundup-server``.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
16
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
17 The Tracker
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
18 -----------
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
19
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
20 We'll be referring to the term tracker a lot from now on. A tracker is a
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
21 directory in your filesystem that is where all the information about a live
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
22 issue
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
23 tracker database is stored. The data that is entered as issues, the users who
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
24 access the database and the definition of the database itself all reside there:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
25
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
26 Hyperdatabase
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
27 This is the lowest component of Roundup and is where all the issues,
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
28 users, file attachments and messages are stored.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
29
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
30 Database schema
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
31 This describes the content of the hyperdatabase - what fields are stored
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
32 for issues, what user information, etc. Being stored in the tracker,
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
33 this allows it to be customised for a particular application. It also
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
34 means that changes in the Roundup core code do not affect a running
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
35 tracker.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
36
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
37 Web Interface
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
38 The web interface templates are defined in the tracker too - and the
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
39 actual CGI interface class is defined (mostly using base classes in the
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
40 Roundup core code) so it, like the database, may be customised for each
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
41 tracker in use.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
42
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
43 Trackers are created using the ``roundup-admin`` tool.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
44
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
45 Command Line Tool
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
46 -----------------
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
47
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
48 To set up a new tracker, run "``roundup-admin install``". You will be
979
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
49 asked a few questions:
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
50
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
51 1. Tracker home directory
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
52 2. Schema to use
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
53 3. Database back-end to use
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
54
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
55 Once you've chosen these, roundup will install the tracker for you. It will
979
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
56 then indicate that you should configure some more information in the
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
57 file "``config.py``" in the tracker home. It
979
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
58 should be edited before roundup is initialised, and may have the following
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
59 variable declarations:
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
60
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
61 MAILHOST
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
62 The SMTP mail host that roundup will use to send mail
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
63 MAIL_DOMAIN
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
64 The domain name used for email addresses
1096
fa7df238e2d4 More cleaning up of configuration, and the "instance" -> "tracker" renaming.
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
65 TRACKER_WEB
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
66 The web address of the issue tracker's web interface
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
67
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
68 The email addresses used by the system by default are:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
69
1096
fa7df238e2d4 More cleaning up of configuration, and the "instance" -> "tracker" renaming.
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
70 TRACKER_EMAIL: ``issue_tracker@MAIL_DOMAIN``
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
71 submissions of issues
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
72
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
73 ADMIN_EMAIL: ``roundup-admin@MAIL_DOMAIN``
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
74 roundup's internal use (problems, etc)
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
75
979
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
76 You may also alter the default schema - see the `customisation`_ documentation
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
77 for more info on both configuration variables and schema modifications.
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
78
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
79 Once you're happy (and note that you can change any of this after the tracker
979
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
80 is initialised too!) you must run "``roundup-admin initialise``".
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
81
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
82 You should also think about whether there is going to be controlled access
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
83 to the
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
84 tracker on the machine the tracker is running on. That is, who can
979
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
85 actually make
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
86 changes to the database using the roundup-admin tool. See the section on
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
87 Users_and_Access_Control for information on how to secure your tracker from the
979
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
88 start.
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
89
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
90 E-Mail Interface
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
91 ----------------
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
92
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
93 Setup 1: As a mail alias pipe process
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
94 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
95
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
96 Set up a mail alias called "issue_tracker" as (include the quote marks):
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
97 "``|/usr/bin/python /usr/local/bin/roundup-mailgw <tracker_home>``"
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
98
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
99 In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh so
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
100 sendmail will accept the pipe command. In that case, symlink
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
101 ``/etc/smrsh/roundup-mailgw`` to "``/usr/local/bin/roundup-mailgw``" and change
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
102 the command to::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
103
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
104 |roundup-mailgw <tracker_home>
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
105
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
106 To test the mail gateway on unix systems, try::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
107
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
108 echo test |mail -s '[issue] test' issue_tracker@your.domain
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
109
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
110
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
111 Setup 2: As a regular cron job using a mailbox source
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
112 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
113
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
114 Set ``roundup-mailgw`` up to run every 10 minutes or so. For example::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
115
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
116 10 * * * * /usr/local/bin/roundup-mailgw <tracker_home> mailbox <mail_spool_file>
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
117
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
118 Where the ``mail_spool_file`` argument is the location of the roundup submission
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
119 user's mail spool. On most systems, the spool for a user "issue_tracker"
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
120 will be "``/var/mail/issue_tracker``".
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
121
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
122 Setup 3: As a regular cron job using a POP source
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
123 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
124
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
125 To retrieve from a POP mailbox, use a similar cron entry to the mailbox one::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
126
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
127 10 * * * * /usr/local/bin/roundup-mailgw <tracker_home> pop <pop_spec>
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
128
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
129 where pop_spec is "``username:password@server``" that specifies the roundup
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
130 submission user's POP account name, password and server.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
131
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
132
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
133 Web Interface
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
134 -------------
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
135
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
136 This software will work through apache or stand-alone.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
137
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
138 Stand-alone:
1096
fa7df238e2d4 More cleaning up of configuration, and the "instance" -> "tracker" renaming.
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
139 1. Edit roundup-server at the top - ``TRACKER_HOMES`` needs to know
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
140 about your tracker. You may also specify the values for
1096
fa7df238e2d4 More cleaning up of configuration, and the "instance" -> "tracker" renaming.
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
141 ``TRACKER_HOMES`` on the command-line using "name=home" pairs.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
142
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
143 2. "``roundup-server [-p port] (name=tracker_home)*``" (hostname may be "")
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
144
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
145 3. Load up the page "``/<tracker name>/index``" where tracker name is the name
1096
fa7df238e2d4 More cleaning up of configuration, and the "instance" -> "tracker" renaming.
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
146 you nominated in ``TRACKER_HOMES``.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
147
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
148 Apache:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
149 1. The CGI script is found in the cgi-bin directory of the roundup
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
150 distribution.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
151
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
152 2. Make sure roundup.cgi is executable. Edit it at the top -
1096
fa7df238e2d4 More cleaning up of configuration, and the "instance" -> "tracker" renaming.
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
153 ``TRACKER_HOMES`` needs to know about your tracker.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
154
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
155 3. Edit your "``/etc/httpd/conf/httpd.conf``" and make sure that the
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
156 "``/home/httpd/html/roundup/roundup.cgi``" script will be treated as a CGI script.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
157
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
158 4. Re-start your apache to re-load the config if necessary.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
159
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
160 5. Load up the page "``/roundup/roundup.cgi/index/``" where tracker name is the
1096
fa7df238e2d4 More cleaning up of configuration, and the "instance" -> "tracker" renaming.
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
161 name you nominated in ``TRACKER_HOMES``.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
162
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
163 6. To use the CGI script unchanged, which allows much easier updates, add
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
164 these directives to your "httpd.conf"::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
165
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
166 SetEnv ROUNDUP_LOG "/var/log/roundup.log"
1096
fa7df238e2d4 More cleaning up of configuration, and the "instance" -> "tracker" renaming.
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
167 SetEnv TRACKER_HOMES "Default=/usr/local/share/roundup/trackers/Default"
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
168 SetEnv ROUNDUP_DEBUG "0"
991
79129f013153 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 979
diff changeset
169
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
170 7. On Windows, write a batch file "roundup.bat" similar to the one below and
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
171 place it into your cgi-bin directory::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
172
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
173 @echo off
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
174 set ROUNDUP_LOG=c:\Python21\share\roundup\cgi.log
1096
fa7df238e2d4 More cleaning up of configuration, and the "instance" -> "tracker" renaming.
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
175 set TRACKER_HOMES=Default=c:\Python21\share\roundup\trackers\Default;
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
176 set ROUNDUP_DEBUG=0
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
177 c:\Python21\python.exe c:\Python21\share\roundup\cgi-bin\roundup.cgi
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
178
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
179
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
180 Users
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
181 -----
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
182
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
183 Users and permissions
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
184 ~~~~~~~~~~~~~~~~~~~~~
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
185
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
186 By default, roundup automatically creates one user when the tracker database is
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
187 initialised (using roundup-admin init). The user is "admin" and the password is
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
188 the one you supply at that time.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
189
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
190 If users attempt to use roundup in any manner and are not identified to roundup,
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
191 they will be using the database in a read-only mode. That is, if roundup doesn't
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
192 know who they are, they can't change anything. This has the following
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
193 repurcussions:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
194
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
195 Command-line interface
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
196 The data modification commands (create, init, retire, set) are performed
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
197 as the "admin" user. It is therefore important that the database be
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
198 protected by the filesystem if protection is required. On a Unix system,
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
199 the easiest and most flexible method of doing so is:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
200
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
201 1. Add a new user and group to your system (e.g. "issue_tracker")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
202
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
203 2. When creating a new tracker home, use the following commands
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
204 (substituting tracker_home for the directory you want to use)::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
205
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
206 mkdir tracker_home
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
207 chown issue_tracker:issue_tracker tracker_home
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
208 chmod g+rwxs tracker_home
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
209 roundup-admin -i tracker_home init
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
210
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
211 3. Now, edit the /etc/group line for the issue_tracker group so it
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
212 includes the unix logins of all the users who are going to
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
213 administer your roundup tracker. If you're running the web or mail
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
214 gateways, then be sure to include those users in the group too (on
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
215 some Linux systems, these users are "www" or "apache" and "mail".)
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
216
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
217 E-Mail interface
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
218 Users are identified by e-mail address - a new user entry will be created
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
219 for any e-mail address that is not recognised, so users are always
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
220 identified by roundup.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
221
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
222 Web interface
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
223 Unidentified users have read-only access. If the users database has an
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
224 entry with the username "anonymous", then unidentified users are
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
225 automatically logged in as that user. This gives them write access.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
226
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
227 **anonymous access and the ANONYMOUS_* configurations.**
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
228
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
229
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
230 Adding users
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
231 ~~~~~~~~~~~~
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
232
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
233 To add users, use one of the following interfaces:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
234
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
235 1. On the web, access the URL .../<tracker name>/newuser to bring up a form
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
236 which may be used to add a new user.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
237
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
238 2. On the command-line, use::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
239
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
240 roundup-admin -i <tracker home> create user username=bozo password=bozo
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
241 address=richard@clown.org
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
242
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
243 Supply the admin username and password. roundup-admin will print the id
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
244 of the new user.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
245
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
246 3. Any e-mail sent to roundup from an address that doesn't match an existing
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
247 user in the database will result in a new user entry being created for
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
248 that user.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
249
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
250
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
251 Issues
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
252 ------
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
253
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
254 To add issues, use one of the following interfaces:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
255
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
256 1. On the web, access the URL .../<tracker name>/newissue to bring up a
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
257 form which may be used to add a new issue.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
258
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
259 2. On the command-line, use::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
260
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 991
diff changeset
261 roundup-admin -i <tracker home> create issue title="test issue"
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
262
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
263 Supply the admin username and password. roundup-admin will print the id
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
264 of the new issue.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
265
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
266 3. Any e-mail sent to roundup with the subject line containing [issue] will
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
267 automatically created a new issue in the database using the contents of
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
268 the e-mail.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
269
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
270 -----------------
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
271
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
272 Back to `Table of Contents`_
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
273
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
274 Next: `User Guide`_
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
275
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
276 .. _`table of contents`: index.html
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
277 .. _`user guide`: user_guide.html
979
f36ffa50374f Fixes to doc
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
278 .. _`customisation`: customizing.html
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
279
Roundup Issue Tracker: http://roundup-tracker.org/