doc/installation.txt

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