doc/installation.txt

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