Mercurial > p > roundup > code

comparison doc/getting_started.txt @ 1089:43ab730ee194

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