doc/installation.txt

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