doc/getting_started.txt

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