doc/installation.txt

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