doc/installation.stx

   1 Installing Roundup
   2 ==================
   3
   4 `Table of contents`_
   5
   6 - Overview_
   7
   8   - `Classic Template`_
   9   - `Extended Template`_
  10
  11 - Prerequisites_
  12
  13   - `Testing your Python`_
  14
  15 - `Getting Roundup`_
  16 - `Installation`_
  17 - `Further Reading`_
  18 - `Platform-Specific Notes`_
  19
  20 Overview
  21 ========
  22
  23 Broken out separately, there are several conceptual pieces to a
  24 Roundup installation:
  25
  26 Roundup support code
  27  Installed into your Python install's lib directory
  28
  29 Roundup scripts
  30  These include the email gateway, the roundup
  31  HTTP server, the roundup administration command-line interface, etc.
  32
  33 Roundup instances
  34  Instances consist of core support files, issues
  35  (be they bug reports or otherwise), instance configuration file(s),
  36  etc.  Roundup instances also adhere to a specific "Template" which
  37  defines the fields usable/assignable on a per-issue basis.  A
  38  description of the provided templates follows.
  39
  40 Classic Template
  41 ----------------
  42
  43 The classic template is the one defined in the `Roundup Specification`_. It
  44 holds issues which have priorities and statuses. Each issue may also have a
  45 set of messages which are disseminated to the issue's list of nosy users.
  46
  47
  48 Extended Template
  49 -----------------
  50
  51 The extended template adds additional information to issues: product,
  52 platform, version, targetversion and supportcall.
  53 There is an additional class for
  54 handling support calls, which includes a time log, customername, rate and
  55 source.
  56
  57 The priorty class has different default entries too: "fatal-bug", "bug",
  58 "usability" and "feature".
  59
  60 Users of this template will want to change the contents of the product
  61 class as soon as the instance is created.
  62
  63
  64 Prerequisites
  65 =============
  66
  67 Python 2.1.1 or newer with a functioning anydbm or bsddb module.
  68
  69 Download the latest version from http://www.python.org/.
  70
  71
  72 Testing your Python
  73 -------------------
  74
  75 Run ``"python -c 'import test;test.go()'"`` and make sure there
  76 are no errors.  If there are errors, please let us know!
  77
  78
  79 Getting Roundup
  80 ===============
  81
  82 Download the latest version from http://roundup.sf.net/.
  83
  84
  85 Installation
  86 ============
  87
  88 Set aside 15-30 minutes.
  89
  90 1. To install the Roundup support code into your Python tree and
  91    Roundup scripts into /usr/local/bin::
  92
  93        python setup.py install
  94
  95    If you would like to place the Roundup scripts in a directory other
  96    than ``/usr/local/bin``, use the ``--install-scripts`` option as follows,
  97    replacing ``/opt/roundup/bin`` with the location where you would like
  98    the scripts to reside::
  99
 100        python setup.py install --install-scripts=/opt/roundup/bin
 101
 102 2. To create a Roundup instance (necessary to do before you can
 103    use the software in any real fashion):
 104
 105    a. (Optional) If you intend to keep your roundup instances
 106       under one top level directory which does not exist yet,
 107       you should create that directory now.  Example:
 108
 109          mkdir /opt/roundup/instances
 110
 111    b. Either add the Roundup script location to your ``PATH``
 112       environment variable or specify the full path to
 113       the command in the next step.
 114
 115   c.  ``roundup-admin init``
 116
 117       You will be asked a series of questions.  A description of
 118       the Roundup-provided templates can be found under the Overview_::
 119
 120           Enter instance home: /opt/roundup/instances/support
 121           Templates: classic, extended
 122           Select template [classic]: classic
 123           Back ends: anydbm, bsddb
 124           Select backend [anydbm]: anydbm
 125           Admin Password:
 126                  Confirm:
 127
 128 3. Each instance ideally should have its own UNIX group, so create
 129    a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
 130    you're using NIS).  To continue with my examples so far, I would
 131    create the UNIX group 'support', although the name of the UNIX
 132    group does not have to be the same as the instance name.  To this
 133    'support' group I then add all of the UNIX usernames who will be
 134    working with this Roundup instance.  In addition to 'real' users,
 135    the Roundup email gateway will need to have permissions to this
 136    area as well, so add the user your mail service runs as to the
 137    group.  The UNIX group might then look like::
 138
 139         support:*:1002:jblaine,samh,geezer,mail
 140
 141    If you intend to use the web interface (as most people do), you
 142    should also add the username your web server runs as to the group.
 143    My group now looks like this::
 144
 145         support:*:1002:jblaine,samh,geezer,mail,apache
 146
 147 4. Configure your new instance by editing the file ``instance_config.py``
 148    located in the instance home you specified in step 2c above.  This
 149    file is Python code and must adhere to Python syntax rules, but
 150    don't be daunted if you do not know Python - it should look pretty
 151    straightfoward if you carefully read the comments in the file.
 152
 153 5. There are two supported ways to get emailed issues into the
 154    Roundup instance.  You should pick ONE of the following, both
 155    of which will continue my example setup from above:
 156
 157    a. Set up a mail alias called "support" as::
 158
 159        "|/opt/roundup/bin/roundup-mailgw /opt/roundup/instances/support"
 160
 161       If you use Sendmail's ``smrsh`` mechanism, please read the notes
 162       under 'Platform-Specific Notes'
 163
 164    b. OR... Configure roundup-mailgw to run every 10 minutes or
 165       so via ``cron``.  My cron job would be (these 2 lines all on one
 166       line)::
 167
 168        10 * * * * /opt/roundup/bin/roundup-mailgw
 169                 /opt/roundup/instances/support /var/mail/support
 170
 171 6. TODO (mention perms)
 172
 173 7. Test the email gateway.  Under most flavors of UNIX, this
 174    can be done by::
 175
 176      echo test | mail -s '[issue] test' support@YOUR_DOMAIN_HERE
 177
 178 TODO (finish)
 179
 180
 181 Further Reading
 182 ===============
 183
 184 If you intend to use Roundup with anything other than the defualt
 185 templates, if you would like to hack on Roundup, or if you would
 186 like implementation details, you should read `Customising Roundup`_.
 187
 188
 189 Platform-Specific Notes
 190 =======================
 191
 192 Sendmail smrsh
 193 --------------
 194
 195 If you use Sendmail's ``smrsh`` mechanism, you will need to tell
 196 smrsh that roundup-mailgw is a valid/trusted mail handler
 197 before it will work.
 198
 199 This is usually done via the following 2 steps:
 200
 201 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
 202    which points to the full path of your actual ``roundup-mailgw``
 203    script.
 204
 205 2. change your alias to ``"|roundup-mailgw <instance_home>"``
 206
 207
 208 Linux
 209 -----
 210
 211 Python 2.1.1 as shipped with SuSE7.3 might be missing module
 212 ``_weakref``.
 213
 214 -------------------------------------------------------------------------------
 215
 216 Next: `Getting Started`_
 217
 218 .. _`table of contents`: index.html
 219 .. _`getting started`: getting_started.html
 220 .. _`roundup specification`: spec.html
 221 .. _`customising roundup`: customizing.html
 222
 223 $Id: installation.stx,v 1.3 2002-03-09 22:46:52 richard Exp $