doc/installation.txt

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