doc/installation.txt

   1 ==================
   2 Installing Roundup
   3 ==================
   4
   5 :Version: $Revision: 1.24 $
   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 trackers
  24  Trackers consist of core support files, issues
  25  (be they bug reports or otherwise), tracker configuration file(s),
  26  etc.  Roundup trackers 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 Backends
  39 --------
  40
  41 The actual storage of Roundup tracker information is handled by backends.
  42 There's several to choose from, each with benefits and limitations:
  43
  44 **anydbm**
  45   This backend is guaranteed to work on any system that Python runs on. It
  46   will generally choose the best *dbm backend that is available on your system
  47   (from the list dbhash, gdbm, dbm, dumbdbm). It is the least scaleable of all
  48   backends, but performs well enough for a smallish tracker (a couple of
  49   thousand issues, under fifty users, ...).
  50 **bsddb**
  51   This effectively the same as anydbm, but uses the bsddb backend. This allows
  52   it to gain some performance and scaling benefits.
  53 **bsddb3**
  54   Again, this effectively the same as anydbm, but uses the bsddb3 backend.
  55   This allows it to gain some performance and scaling benefits.
  56 **sqlite**
  57   This uses the SQLite embedded RDBMS to provide a fast, scaleable backend.
  58   There are no limitations.
  59 **gadfly**
  60   This is a proof-of-concept relational database backend, not really intended
  61   for actual production use, although it can be. It uses the Gadfly RDBMS
  62   to store data. It is unable to perform string searches due to gadfly not
  63   having a LIKE operation. It should scale well, assuming a client/server
  64   setup is used.
  65 **metakit**
  66   This backend is implemented over the metakit storage system, using Mk4Py as
  67   the interface. It scales much better than the *dbm backends, but has some
  68   missing features:
  69
  70   - you may not unset properties once they are set
  71   - journal retrieval is not implemented
  72
  73
  74 Prerequisites
  75 =============
  76
  77 Python 2.1.1 or newer with a functioning anydbm or bsddb module. Download the
  78 latest version from http://www.python.org/. It is highly recommended that
  79 users install the latest patch version of python - 2.1.3 or 2.2.1 - as these
  80 contain many fixes to serious bugs.
  81
  82 If you want to use Berkeley DB bsddb3 with Roundup, use version 3.3.0 or
  83 later. Download the latest version from http://pybsddb.sourceforge.net/.
  84
  85
  86 Getting Roundup
  87 ===============
  88
  89 Download the latest version from http://roundup.sf.net/.
  90
  91 Testing your Python
  92 -------------------
  93
  94 Once you've unpacked roundup's source, run ``python ./run_tests`` in the
  95 source directory and make sure there are no errors.
  96 If there are errors, please let us know!
  97
  98 If the above fails, you may be using the wrong version of python. Try
  99 ``python2 ./run_tests``. If that works, you will need to substitute
 100 ``python2`` for ``python`` in all further commands you use in relation to
 101 Roundup -- from installation and scripts.
 102
 103
 104 Installation
 105 ============
 106
 107 Set aside 15-30 minutes. Please make sure you're using a supported version of
 108 Python -- see `testing your python`_. There's three sections to this
 109 installation guide:
 110
 111 1. `basic installation steps`_ that all installers must follow
 112 2. `shared environment steps`_ to take if you're installing on a shared
 113     UNIX machine and want to restrict local access to roundup
 114 3. `internet setup`_ steps to take if your tracker is to be used by the wider
 115     internet community
 116
 117 Most users will only need to follow the first step, since the environment will
 118 be a trusted one.
 119
 120
 121 Basic Installation Steps
 122 ------------------------
 123
 124 1. To install the Roundup support code into your Python tree and
 125    Roundup scripts into /usr/local/bin::
 126
 127        python setup.py install
 128
 129    If you would like to place the Roundup scripts in a directory other
 130    than ``/usr/local/bin``, then specify the preferred location with
 131    ``--install-script``. For example, to install them in
 132    ``/opt/roundup/bin``::
 133
 134        python setup.py install --install-scripts=/opt/roundup/bin
 135
 136 2. To create a Roundup tracker (necessary to do before you can
 137    use the software in any real fashion):
 138
 139    a. (Optional) If you intend to keep your roundup trackers
 140       under one top level directory which does not exist yet,
 141       you should create that directory now.  Example:
 142
 143          mkdir /opt/roundup/trackers
 144
 145    b. Either add the Roundup script location to your ``PATH``
 146       environment variable or specify the full path to
 147       the command in the next step.
 148
 149    c.  ``roundup-admin install``
 150
 151       You will be asked a series of questions.  A description of
 152       the Roundup-provided templates can be found under the Overview_::
 153
 154           Enter tracker home: /opt/roundup/trackers/support
 155           Templates: classic, extended
 156           Select template [classic]: classic
 157           Back ends: anydbm, bsddb
 158           Select backend [anydbm]: anydbm
 159
 160       You will now be directed to edit the tracker configuration and
 161       initial schema. See `Customising Roundup`_ for details on configuration
 162       and schema changes. Note that you may change any of the configuration
 163       after you've initialised the tracker - it's just better to have valid
 164       values for this stuff now.
 165
 166    d.  ``roundup-admin initialise``
 167
 168       This step initialises the tracker database. You will need to supply
 169       an admin password at this step. You will be prompted::
 170
 171           Admin Password:
 172                  Confirm:
 173
 174       Once this is done, the tracker has been created.
 175
 176 3. XXX Set up the CGI interface
 177
 178 4. XXX Set up the mail gateway
 179
 180
 181 Shared Environment Steps
 182 ------------------------
 183
 184 Each tracker ideally should have its own UNIX group, so create
 185 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
 186 you're using NIS).  To continue with my examples so far, I would
 187 create the UNIX group 'support', although the name of the UNIX
 188 group does not have to be the same as the tracker name.  To this
 189 'support' group I then add all of the UNIX usernames who will be
 190 working with this Roundup tracker.  In addition to 'real' users,
 191 the Roundup email gateway will need to have permissions to this
 192 area as well, so add the user your mail service runs as to the
 193 group.  The UNIX group might then look like::
 194
 195      support:*:1002:jblaine,samh,geezer,mail
 196
 197 If you intend to use the web interface (as most people do), you
 198 should also add the username your web server runs as to the group.
 199 My group now looks like this::
 200
 201      support:*:1002:jblaine,samh,geezer,mail,apache
 202
 203 The tracker "db" directory should be chmod'ed g+sw so that the group can
 204 write to the database, and any new files created in the database will be owned
 205 by the group.
 206
 207 An alternative to the above is to create a new user who has the sole
 208 responsibility of running roundup. This user:
 209
 210 1. runs the CGI interface daemon
 211 2. runs regular polls for email
 212 3. runs regular checks (using cron) to ensure the daemon is up
 213 4. optionally has no login password so that nobody but the "root" user
 214    may actually login and play with the roundup setup.
 215
 216 Internet Setup
 217 --------------
 218
 219 1. There are two supported ways to get emailed issues into the
 220    Roundup tracker.  You should pick ONE of the following, both
 221    of which will continue my example setup from above:
 222
 223    a. Set up a mail alias called "support" as::
 224
 225        "|/opt/roundup/bin/roundup-mailgw /opt/roundup/trackers/support"
 226
 227       If you use Sendmail's ``smrsh`` mechanism, please read the notes
 228       under 'Platform-Specific Notes'
 229
 230    b. OR... Configure roundup-mailgw to run every 10 minutes or
 231       so via ``cron``.  My cron job would be (these 2 lines all on one
 232       line)::
 233
 234        10 * * * * /opt/roundup/bin/roundup-mailgw
 235                 /opt/roundup/trackers/support /var/mail/support
 236
 237    If you don't want to use the email component of Roundup, then remove the
 238    "``nosyreator.py``" module from your tracker "``detectors``" directory.
 239
 240 2. Test the email gateway.  Under most flavors of UNIX, this
 241    can be done by::
 242
 243      echo test | mail -s '[issue] test' support@YOUR_DOMAIN_HERE
 244
 245 XXX mention HTTPS
 246 XXX mention Basic vs. cookie auth
 247
 248
 249 Upgrading
 250 =========
 251
 252 Read the separate `upgrading document`_, which describes the steps needed to
 253 upgrade existing tracker trackers for each version of Roundup that is
 254 released.
 255
 256
 257 ZRoundup
 258 ========
 259
 260 Install roundup as usual (see installation_).
 261
 262 ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
 263 your Products directory either in an TRACKER_HOME/Products or the Zope
 264 code tree lib/python/Products.
 265
 266 You will need to create the tracker using the roundup-admin tool (step 2 in
 267 installation_).
 268
 269 When you next (re)start up Zope, you will be able to add a ZRoundup object
 270 that interfaces to your new tracker.
 271
 272
 273 Further Reading
 274 ===============
 275
 276 If you intend to use Roundup with anything other than the defualt
 277 templates, if you would like to hack on Roundup, or if you would
 278 like implementation details, you should read `Customising Roundup`_.
 279
 280
 281 Platform-Specific Notes
 282 =======================
 283
 284 Sendmail smrsh
 285 --------------
 286
 287 If you use Sendmail's ``smrsh`` mechanism, you will need to tell
 288 smrsh that roundup-mailgw is a valid/trusted mail handler
 289 before it will work.
 290
 291 This is usually done via the following 2 steps:
 292
 293 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
 294    which points to the full path of your actual ``roundup-mailgw``
 295    script.
 296
 297 2. change your alias to ``"|roundup-mailgw <tracker_home>"``
 298
 299
 300 Linux
 301 -----
 302
 303 Python 2.1.1 as shipped with SuSE7.3 might be missing module
 304 ``_weakref``.
 305
 306 -------------------------------------------------------------------------------
 307
 308 Back to `Table of Contents`_
 309
 310 Next: `Getting Started`_
 311
 312 .. _`table of contents`: index.html
 313 .. _`getting started`: getting_started.html
 314 .. _`roundup specification`: spec.html
 315 .. _`customising roundup`: customizing.html
 316 .. _`upgrading document`: upgrading.html
 317