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