doc/installation.txt

   1 ==================
   2 Installing Roundup
   3 ==================
   4
   5 :Version: $Revision: 1.20 $
   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`_. There's three sections to this
  89 installation guide:
  90
  91 1. `basic installation steps`_ that all installers must follow
  92 2. `shared environment steps`_ to take if you're installing on a shared
  93     UNIX machine and want to restrict local access to roundup
  94 3. `internet setup`_ steps to take if your tracker is to be used by the wider
  95     internet community
  96
  97 Most users will only need to follow the first step, since the environment will
  98 be a trusted one.
  99
 100
 101 Basic Installation Steps
 102 ~~~~~~~~~~~~~~~~~~~~~~~~
 103
 104 1. To install the Roundup support code into your Python tree and
 105    Roundup scripts into /usr/local/bin::
 106
 107        python setup.py install
 108
 109    If you would like to place the Roundup scripts in a directory other
 110    than ``/usr/local/bin``, then specify the preferred location with
 111    ``--install-script``. For example, to install them in
 112    ``/opt/roundup/bin``::
 113
 114        python setup.py install --install-scripts=/opt/roundup/bin
 115
 116 2. To create a Roundup instance (necessary to do before you can
 117    use the software in any real fashion):
 118
 119    a. (Optional) If you intend to keep your roundup instances
 120       under one top level directory which does not exist yet,
 121       you should create that directory now.  Example:
 122
 123          mkdir /opt/roundup/instances
 124
 125    b. Either add the Roundup script location to your ``PATH``
 126       environment variable or specify the full path to
 127       the command in the next step.
 128
 129    c.  ``roundup-admin install``
 130
 131       You will be asked a series of questions.  A description of
 132       the Roundup-provided templates can be found under the Overview_::
 133
 134           Enter instance home: /opt/roundup/instances/support
 135           Templates: classic, extended
 136           Select template [classic]: classic
 137           Back ends: anydbm, bsddb
 138           Select backend [anydbm]: anydbm
 139
 140       You will now be directed to edit the instance configuration and
 141       initial schema. See `Customising Roundup`_ for details on configuration
 142       and schema changes. Note that you may change any of the configuration
 143       after you've initialised the instance - it's just better to have valid
 144       values for this stuff now.
 145
 146    d.  ``roundup-admin initialise``
 147
 148       This step initialises the instance database. You will need to supply
 149       an admin password at this step. You will be prompted::
 150
 151           Admin Password:
 152                  Confirm:
 153
 154       Once this is done, the instance has been created.
 155
 156 3. XXX Set up the CGI interface
 157
 158 4. XXX Set up the mail gateway
 159
 160
 161 Shared Environment Steps
 162 ~~~~~~~~~~~~~~~~~~~~~~~~
 163
 164 Each instance ideally should have its own UNIX group, so create
 165 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
 166 you're using NIS).  To continue with my examples so far, I would
 167 create the UNIX group 'support', although the name of the UNIX
 168 group does not have to be the same as the instance name.  To this
 169 'support' group I then add all of the UNIX usernames who will be
 170 working with this Roundup instance.  In addition to 'real' users,
 171 the Roundup email gateway will need to have permissions to this
 172 area as well, so add the user your mail service runs as to the
 173 group.  The UNIX group might then look like::
 174
 175      support:*:1002:jblaine,samh,geezer,mail
 176
 177 If you intend to use the web interface (as most people do), you
 178 should also add the username your web server runs as to the group.
 179 My group now looks like this::
 180
 181      support:*:1002:jblaine,samh,geezer,mail,apache
 182
 183 An alternative to the above is to create a new user who has the sole
 184 responsibility of running roundup. This user:
 185
 186 1. runs the CGI interface daemon
 187 2. runs regular polls for email
 188 3. runs regular checks (using cron) to ensure the daemon is up
 189 4. optionally has no login password so that nobody but the "root" user
 190    may actually login and play with the roundup setup.
 191
 192
 193 Internet Setup
 194 ~~~~~~~~~~~~~~
 195
 196 1. There are two supported ways to get emailed issues into the
 197    Roundup instance.  You should pick ONE of the following, both
 198    of which will continue my example setup from above:
 199
 200    a. Set up a mail alias called "support" as::
 201
 202        "|/opt/roundup/bin/roundup-mailgw /opt/roundup/instances/support"
 203
 204       If you use Sendmail's ``smrsh`` mechanism, please read the notes
 205       under 'Platform-Specific Notes'
 206
 207    b. OR... Configure roundup-mailgw to run every 10 minutes or
 208       so via ``cron``.  My cron job would be (these 2 lines all on one
 209       line)::
 210
 211        10 * * * * /opt/roundup/bin/roundup-mailgw
 212                 /opt/roundup/instances/support /var/mail/support
 213
 214    If you don't want to use the email component of Roundup, then remove the
 215    "``nosyreator.py``" module from your instance "``detectors``" directory.
 216
 217 2. Test the email gateway.  Under most flavors of UNIX, this
 218    can be done by::
 219
 220      echo test | mail -s '[issue] test' support@YOUR_DOMAIN_HERE
 221
 222 XXX mention HTTPS
 223 XXX mention Basic vs. cookie auth
 224
 225
 226 Upgrading
 227 =========
 228
 229 Read the separate `upgrading document`_, which describes the steps needed to
 230 upgrade existing tracker instances for each version of Roundup that is
 231 released.
 232
 233
 234 ZRoundup
 235 ========
 236
 237 Install roundup as usual (see installation_).
 238
 239 ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
 240 your Products directory either in an INSTANCE_HOME/Products or the Zope
 241 code tree lib/python/Products.
 242
 243 You will need to create the instance using the roundup-admin tool (step 2 in
 244 installation_).
 245
 246 When you next (re)start up Zope, you will be able to add a ZRoundup object
 247 that interfaces to your new instance.
 248
 249
 250 Further Reading
 251 ===============
 252
 253 If you intend to use Roundup with anything other than the defualt
 254 templates, if you would like to hack on Roundup, or if you would
 255 like implementation details, you should read `Customising Roundup`_.
 256
 257
 258 Platform-Specific Notes
 259 =======================
 260
 261 Sendmail smrsh
 262 --------------
 263
 264 If you use Sendmail's ``smrsh`` mechanism, you will need to tell
 265 smrsh that roundup-mailgw is a valid/trusted mail handler
 266 before it will work.
 267
 268 This is usually done via the following 2 steps:
 269
 270 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
 271    which points to the full path of your actual ``roundup-mailgw``
 272    script.
 273
 274 2. change your alias to ``"|roundup-mailgw <instance_home>"``
 275
 276
 277 Linux
 278 -----
 279
 280 Python 2.1.1 as shipped with SuSE7.3 might be missing module
 281 ``_weakref``.
 282
 283 -------------------------------------------------------------------------------
 284
 285 Back to `Table of Contents`_
 286
 287 Next: `Getting Started`_
 288
 289 .. _`table of contents`: index.html
 290 .. _`getting started`: getting_started.html
 291 .. _`roundup specification`: spec.html
 292 .. _`customising roundup`: customizing.html
 293 .. _`upgrading document`: upgrading.html
 294