Mercurial > p > roundup > code

annotate doc/getting_started.txt @ 686:c52122f38c9b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documentation cleanup, added info for potential (and current) developers
author Richard Jones <richard@users.sourceforge.net>
date Wed, 10 Apr 2002 23:55:36 +0000
parents e429649ed124
children b38f4f95bffd
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1 Getting Started
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2 ===============
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
4 :Version: $Revision: 1.2 $
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
5
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
6 .. contents::
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
7
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
8
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
9 The following instructions assume that you have installed roundup. If you
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
10 haven't, you may still proceed - just run the commands as
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
11 "``PYTHONPATH=. python roundup/scripts/roundup_admin.py``" for
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
12 ``roundup-admin`` and
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
13 "``PYTHONPATH=. python roundup/scripts/roundup_server.py``" for
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
14 ``roundup-server``.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
15
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
16 The Instance
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
17 ------------
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
18
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
19 We'll be referring to the term instance a lot from now on. An instance is a
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
20 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
21 issue
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
22 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
23 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
24
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
25 Hyperdatabase
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
26 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
27 users, file attachments and messages are stored.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
28
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
29 Database schema
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
30 This describes the content of the hyperdatabase - what fields are stored
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
31 for issues, what user information, etc. Being stored in the instance,
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
32 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
33 means that changes in the Roundup core code do not affect a running
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
34 instance.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
35
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
36 Web Interface
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
37 The web interface templates are defined in the instance too - and the
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
38 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
39 Roundup core code) so it, like the database, may be customised for each
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
40 instance in use.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
41
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
42 Instances are created using the ``roundup-admin`` tool.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
43
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
44 Command Line Tool
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
45 -----------------
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 To initiliase a new instance, run "``roundup-admin init``". You will be asked a
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
48 series of questions:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
49
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
50 1. Instance home directory
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
51 2. Schema to use
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
52 3. Database back-end to use
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
53 4. Administration user "admin" password.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
54
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
55 You should also think about whether there is going to be controlled access
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
56 to the
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
57 instance on the machine the instance is running on. That is, who can
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
58 actually make
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
59 changes to the database using the roundup-admin tool. See the section on
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
60 Users_and_Access_Control for information on how to secure your instance from the
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
61 start.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
62
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
63 Roundup is configurable using an ``instance_config.py`` file in the instance
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
64 home. It
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
65 should be edited before roundup is used, and may have the following variable
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
66 declarations:
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 MAILHOST
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
69 The SMTP mail host that roundup will use to send mail
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
70 MAIL_DOMAIN
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
71 The domain name used for email addresses
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
72 ISSUE_TRACKER_WEB
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
73 The web address of the issue tracker's web interface
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
74
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
75 The email addresses used by the system by default are:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
76
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
77 ISSUE_TRACKER_EMAIL: ``issue_tracker@MAIL_DOMAIN``
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
78 submissions of issues
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
79
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
80 ADMIN_EMAIL: ``roundup-admin@MAIL_DOMAIN``
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
81 roundup's internal use (problems, etc)
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
82
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
83 E-Mail Interface
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
84 ----------------
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
85
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
86 Setup 1: As a mail alias pipe process
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
87 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
88
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
89 Set up a mail alias called "issue_tracker" as (include the quote marks):
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
90 "``|/usr/bin/python /usr/local/bin/roundup-mailgw <instance_home>``"
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 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
93 sendmail will accept the pipe command. In that case, symlink
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
94 ``/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
95 the command to::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
96
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
97 |roundup-mailgw <instance_home>
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 To test the mail gateway on unix systems, try::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
100
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
101 echo test |mail -s '[issue] test' issue_tracker@your.domain
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
102
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
103
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
104 Setup 2: As a regular cron job using a mailbox source
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
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
107 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
108
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
109 10 * * * * /usr/local/bin/roundup-mailgw <instance_home> mailbox <mail_spool_file>
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 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
112 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
113 will be "``/var/mail/issue_tracker``".
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
114
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
115 Setup 3: As a regular cron job using a POP source
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
116 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 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
119
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
120 10 * * * * /usr/local/bin/roundup-mailgw <instance_home> pop <pop_spec>
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 where pop_spec is "``username:password@server``" that specifies the roundup
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
123 submission user's POP account name, password and server.
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
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
126 Web Interface
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
127 -------------
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 This software will work through apache or stand-alone.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
130
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
131 Stand-alone:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
132 1. Edit roundup-server at the top - ``ROUNDUP_INSTANCE_HOMES`` needs to know
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
133 about your instance. You may also specify the values for
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
134 ``ROUNDUP_INSTANCE_HOMES`` on the command-line using "name=home" pairs.
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 2. "``roundup-server [-p port] (name=instance_home)*``" (hostname may be "")
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 3. Load up the page "``/<instance name>/index``" where instance name is the name
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
139 you nominated in ``ROUNDUP_INSTANCE_HOMES``.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
140
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
141 Apache:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
142 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
143 distribution.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
144
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
145 2. Make sure roundup.cgi is executable. Edit it at the top -
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
146 ``ROUNDUP_INSTANCE_HOMES`` needs to know about your instance.
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 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
149 "``/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
150
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
151 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
152
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
153 5. Load up the page "``/roundup/roundup.cgi/index/``" where instance name is the
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
154 name you nominated in ``ROUNDUP_INSTANCE_HOMES``.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
155
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
156 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
157 these directives to your "httpd.conf"::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
158
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
159 SetEnv ROUNDUP_LOG "/var/log/roundup.log"
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
160 SetEnv ROUNDUP_INSTANCE_HOMES "Default=/usr/local/share/roundup/instances/Default"
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
161 SetEnv ROUNDUP_DEBUG "0"
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 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
164 place it into your cgi-bin directory::
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 @echo off
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
167 set ROUNDUP_LOG=c:\Python21\share\roundup\cgi.log
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
168 set ROUNDUP_INSTANCE_HOMES=Default=c:\Python21\share\roundup\instances\Default;
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
169 set ROUNDUP_DEBUG=0
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
170 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
171
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 Users
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
174 -----
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
175
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
176 Users and permissions
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
177 ~~~~~~~~~~~~~~~~~~~~~
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 By default, roundup automatically creates one user when the instance database is
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
180 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
181 the one you supply at that time.
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 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
184 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
185 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
186 repurcussions:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
187
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
188 Command-line interface
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
189 The data modification commands (create, init, retire, set) are performed
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
190 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
191 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
192 the easiest and most flexible method of doing so is:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
193
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
194 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
195
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
196 2. When creating a new instance home, use the following commands
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
197 (substituting instance_home for the directory you want to use)::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
198
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
199 mkdir instance_home
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
200 chown issue_tracker:issue_tracker instance_home
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
201 chmod g+rwxs instance_home
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
202 roundup-admin -i instance_home init
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
203
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
204 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
205 includes the unix logins of all the users who are going to
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
206 administer your roundup instance. If you're running the web or mail
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
207 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
208 some Linux systems, these users are "www" or "apache" and "mail".)
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
209
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
210 E-Mail interface
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
211 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
212 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
213 identified by roundup.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
214
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
215 Web interface
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
216 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
217 entry with the username "anonymous", then unidentified users are
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
218 automatically logged in as that user. This gives them write access.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
219
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
220 **anonymous access and the ANONYMOUS_* configurations.**
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
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
223 Adding users
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
224 ~~~~~~~~~~~~
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
225
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
226 To add users, use one of the following interfaces:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
227
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
228 1. On the web, access the URL .../<instance name>/newuser to bring up a form
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
229 which may be used to add a new user.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
230
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
231 2. On the command-line, use::
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 roundup-admin -i <instance home> create user username=bozo password=bozo
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
234 address=richard@clown.org
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
235
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
236 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
237 of the new user.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
238
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
239 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
240 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
241 that user.
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
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
244 Issues
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
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
247 To add issues, use one of the following interfaces:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
248
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
249 1. On the web, access the URL .../<instance name>/newissue to bring up a
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
250 form which may be used to add a new issue.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
251
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
252 2. On the command-line, use::
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 roundup-admin -i <instance home> create issue title="test issue"
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
255
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
256 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
257 of the 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 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
260 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
261 the e-mail.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
262
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
263 -----------------
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
264
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
265 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
266
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
267 Next: `User Guide`_
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
268
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
269 .. _`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
270 .. _`user guide`: user_guide.html
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
271
Roundup Issue Tracker: http://roundup-tracker.org/