doc/installation.txt

   1 ==================
   2 Installing Roundup
   3 ==================
   4
   5 :Version: $Revision: 1.15 $
   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. Download the
  58 latest version from http://www.python.org/. It is highly recommended that
  59 users install the latest patch version of python - 2.1.3 or 2.2.1 - as these
  60 contain many fixes to serious bugs.
  61
  62 If you want to use Berkeley DB bsddb3 with Roundup, use version 3.3.0 or
  63 later. Download the latest version from http://pybsddb.sourceforge.net/.
  64
  65
  66 Testing your Python
  67 -------------------
  68
  69 Run ``python ./run_tests`` and make sure there
  70 are no errors.  If there are errors, please let us know!
  71
  72 If the above fails, you may be using the wrong version of python. Try
  73 ``python2 ./run_tests``. If that works, you will need to substitute
  74 ``python2`` for ``python`` in all further commands you use in relation to
  75 Roundup -- from installation and scripts.
  76
  77 Getting Roundup
  78 ===============
  79
  80 Download the latest version from http://roundup.sf.net/.
  81
  82
  83 Installation
  84 ============
  85
  86 Set aside 15-30 minutes. Please make sure you're using a supported version of
  87 Python -- see `testing your python`_.
  88
  89 1. To install the Roundup support code into your Python tree and
  90    Roundup scripts into /usr/local/bin::
  91
  92        python setup.py install
  93
  94    If you would like to place the Roundup scripts in a directory other
  95    than ``/usr/local/bin``, use the ``--install-scripts`` option as follows,
  96    replacing ``/opt/roundup/bin`` with the location where you would like
  97    the scripts to reside::
  98
  99        python setup.py install --install-scripts=/opt/roundup/bin
 100
 101 2. To create a Roundup instance (necessary to do before you can
 102    use the software in any real fashion):
 103
 104    a. (Optional) If you intend to keep your roundup instances
 105       under one top level directory which does not exist yet,
 106       you should create that directory now.  Example:
 107
 108          mkdir /opt/roundup/instances
 109
 110    b. Either add the Roundup script location to your ``PATH``
 111       environment variable or specify the full path to
 112       the command in the next step.
 113
 114    c.  ``roundup-admin install``
 115
 116       You will be asked a series of questions.  A description of
 117       the Roundup-provided templates can be found under the Overview_::
 118
 119           Enter instance home: /opt/roundup/instances/support
 120           Templates: classic, extended
 121           Select template [classic]: classic
 122           Back ends: anydbm, bsddb
 123           Select backend [anydbm]: anydbm
 124
 125       You will now be directed to edit the instance configuration and
 126       initial schema. See `Customising Roundup`_ for details on configuration
 127       and schema changes. Note that you may change any of the configuration
 128       after you've initialised the instance - it's just better to have valid
 129       values for this stuff now.
 130
 131    d.  ``roundup-admin initialise``
 132
 133       This step initialises the instance database. You will need to supply
 134       an admin password at this step. You will be prompted::
 135
 136           Admin Password:
 137                  Confirm:
 138
 139       Once this is done, the instance has been created.
 140
 141 3. Each instance ideally should have its own UNIX group, so create
 142    a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
 143    you're using NIS).  To continue with my examples so far, I would
 144    create the UNIX group 'support', although the name of the UNIX
 145    group does not have to be the same as the instance name.  To this
 146    'support' group I then add all of the UNIX usernames who will be
 147    working with this Roundup instance.  In addition to 'real' users,
 148    the Roundup email gateway will need to have permissions to this
 149    area as well, so add the user your mail service runs as to the
 150    group.  The UNIX group might then look like::
 151
 152         support:*:1002:jblaine,samh,geezer,mail
 153
 154    If you intend to use the web interface (as most people do), you
 155    should also add the username your web server runs as to the group.
 156    My group now looks like this::
 157
 158         support:*:1002:jblaine,samh,geezer,mail,apache
 159
 160 4. Configure your new instance by editing the file ``instance_config.py``
 161    located in the instance home you specified in step 2c above.  This
 162    file is Python code and must adhere to Python syntax rules, but
 163    don't be daunted if you do not know Python - it should look pretty
 164    straightfoward if you carefully read the comments in the file.
 165
 166 5. There are two supported ways to get emailed issues into the
 167    Roundup instance.  You should pick ONE of the following, both
 168    of which will continue my example setup from above:
 169
 170    a. Set up a mail alias called "support" as::
 171
 172        "|/opt/roundup/bin/roundup-mailgw /opt/roundup/instances/support"
 173
 174       If you use Sendmail's ``smrsh`` mechanism, please read the notes
 175       under 'Platform-Specific Notes'
 176
 177    b. OR... Configure roundup-mailgw to run every 10 minutes or
 178       so via ``cron``.  My cron job would be (these 2 lines all on one
 179       line)::
 180
 181        10 * * * * /opt/roundup/bin/roundup-mailgw
 182                 /opt/roundup/instances/support /var/mail/support
 183
 184 6. TODO (mention perms)
 185
 186 7. Test the email gateway.  Under most flavors of UNIX, this
 187    can be done by::
 188
 189      echo test | mail -s '[issue] test' support@YOUR_DOMAIN_HERE
 190
 191
 192 Upgrading
 193 =========
 194
 195 Read the separate `upgrading document`_, which describes the steps needed to
 196 upgrade existing tracker instances for each version of Roundup that is
 197 released.
 198
 199
 200 ZRoundup
 201 ========
 202
 203 Install roundup as usual (see installation_).
 204
 205 ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
 206 your Products directory either in an INSTANCE_HOME/Products or the Zope
 207 code tree lib/python/Products.
 208
 209 You will need to create the instance using the roundup-admin tool (step 2 in
 210 installation_).
 211
 212 When you next (re)start up Zope, you will be able to add a ZRoundup object
 213 that interfaces to your new instance.
 214
 215
 216 Further Reading
 217 ===============
 218
 219 If you intend to use Roundup with anything other than the defualt
 220 templates, if you would like to hack on Roundup, or if you would
 221 like implementation details, you should read `Customising Roundup`_.
 222
 223
 224 Platform-Specific Notes
 225 =======================
 226
 227 Sendmail smrsh
 228 --------------
 229
 230 If you use Sendmail's ``smrsh`` mechanism, you will need to tell
 231 smrsh that roundup-mailgw is a valid/trusted mail handler
 232 before it will work.
 233
 234 This is usually done via the following 2 steps:
 235
 236 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
 237    which points to the full path of your actual ``roundup-mailgw``
 238    script.
 239
 240 2. change your alias to ``"|roundup-mailgw <instance_home>"``
 241
 242
 243 Linux
 244 -----
 245
 246 Python 2.1.1 as shipped with SuSE7.3 might be missing module
 247 ``_weakref``.
 248
 249 -------------------------------------------------------------------------------
 250
 251 Back to `Table of Contents`_
 252
 253 Next: `Getting Started`_
 254
 255 .. _`table of contents`: index.html
 256 .. _`getting started`: getting_started.html
 257 .. _`roundup specification`: spec.html
 258 .. _`customising roundup`: customizing.html
 259 .. _`upgrading document`: upgrading.html
 260