doc/getting_started.txt

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