![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/installation.txt b/doc/installation.txt
index c5fc0e5f70a572d1b6495956d28a846f282ada69..4fada5d489336796a4c10cb32445f69bea7eda93 100644 (file)
--- a/doc/installation.txt
+++ b/doc/installation.txt
Installing Roundup
==================
-:Version: $Revision: 1.65 $
+:Version: $Revision: 1.73 $
.. contents::
Prerequisites
=============
-Python 2.1.3 or newer with a functioning anydbm or bsddb module. Download the
-latest version from http://www.python.org/. It is highly recommended that
-users install the latest patch version of python - 2.1.3, 2.2.3 or 2.3.2 -
-as these contain many fixes to serious bugs.
+Roundup requires Python 2.1.3 or newer with a functioning anydbm or
+bsddb module. Download the latest version from http://www.python.org/.
+It is highly recommended that users install the latest patch version
+of python as these contain many fixes to serious bugs.
If you want to use Berkeley DB bsddb3 with Roundup, use version 3.3.0 or
later. Download the latest version from http://pybsddb.sourceforge.net/.
have to install the win32all package separately (get it from
http://starship.python.net/crew/mhammond/win32/).
+Non-Python2.3 users may need to `install the "CSV" module`_.
+
+Install the "CSV" module
+------------------------
+
+Note: CSV stands for Comma-Separated-Value. These files are used by all
+ manner of programs (eg. spreadsheets) to exchange data.
+
+The "CSV" module is required if you wish to import or export data in the
+tracker, or if you wish to use the online generic class editing facility.
+
+If you're using a version of Python older than 2.3, then you will need to
+install the "CSV" module from `Object Craft`_. Users of Python2.3 and later
+don't need to. If you have a C compiler installed, then download the source
+and follow their installation instructions (simply ``python setup.py
+install``.)
+
+If you're on Windows and don't have a C compiler, then you'll need to
+download the pre-compiled ``csv.pyd`` file and install it. To install, just
+copy it to your Python installation in the ``lib\site-packages`` directory.
+For Python 2.2, this would be::
+
+ c:\python22\lib\site-packages
+
+Once the CSV module is installed, you *must* restart roundup-server if it
+is already running, or the new module won't be detected.
+
+If you're on some other platform and don't have a C compiler, you'll need
+to ask for help on the roundup-users mailing list.
+
+.. _`Object Craft`: http://object-craft.com.au/
+
Getting Roundup
===============
2. `configuring your first tracker`_ that all installers must follow
3. then optionally `configure a web interface`_
4. and optionally `configure an email interface`_
-5. `shared environment steps`_ to take if you're installing on a shared
+5. `UNIX environment steps`_ to take if you're installing on a shared
UNIX machine and want to restrict local access to roundup
+6. `additional language codecs`_
+
+For information about how Roundup installs, see the `administration
+guide`_.
Basic Installation Steps
The actual storage of Roundup tracker information is handled by backends.
There's several to choose from, each with benefits and limitations:
-**anydbm**
- This backend is guaranteed to work on any system that Python runs on. It
- will generally choose the best dbm backend that is available on your system
- (from the list dbhash, gdbm, dbm, dumbdbm). It is the least scaleable of all
- backends, but performs well enough for a smallish tracker (a couple of
- thousand issues, under fifty users, ...).
-**bsddb**
- This effectively the same as anydbm, but uses the bsddb backend. This allows
- it to gain some performance and scaling benefits.
-**bsddb3**
- Again, this effectively the same as anydbm, but uses the bsddb3 backend.
- This allows it to gain some performance and scaling benefits.
-**sqlite**
- This uses the SQLite_ embedded RDBMS to provide a fast, scaleable backend.
- There are no limitations, and it's much faster and more scaleable than the
- dbm backends.
-**mysql**
- Backend for popular RDBMS MySQL. According to benchmarks, this backend works
- much faster than any of \*dbm ones, but slightly slower than metakit and
- sqlite. You must read doc/mysql.txt for additional installation steps and
- requirements.
+========== =========== ===== ==============================
+Name Speed Users Support
+========== =========== ===== ==============================
+anydbm Slowest Few Always available
+bsddb Slow Few Usually available
+sqlite Fastest(*) Few Needs install (SQLite_)
+metakit Fastest(*) Few Needs install (metakit_)
+postgresql Fast Many Needs install/admin (psycopg_)
+mysql Fast Many Needs install/admin (MySQLdb_)
+========== =========== ===== ==============================
+
+**sqlite** and **metakit**
+ These use the embedded database engines SQLite_ and metakit_ to provide
+ very fast backends. They are not suitable for trackers which will have
+ many simultaneous users.
**postgresql**
- Backend for popular RDBMS PostgreSQL. According to benchmarks, this
- backend works much faster than any of \*dbm ones and mysql, but slightly
- slower than metakit and sqlite. You must read doc/postgresql.txt for
+ Backend for popular RDBMS PostgreSQL. You must read doc/postgresql.txt for
additional installation steps and requirements.
-**metakit**
- This backend is implemented over the metakit_ storage system, using Mk4Py as
- the interface. It scales much better than the dbm backends.
-
-You should be wary of using all but the mysql backend with high-volume trackers
-(requests every second or two) as database locking is done on the whole
-database.
+**mysql**
+ Backend for popular RDBMS MySQL. You must read doc/mysql.txt for additional
+ installation steps and requirements.
-You may set your tracker up with the anydbm backend (which is guaranteed to be
-available) and switch to one of the other backends at any time using the
-instructions in the `maintenance documentation`_.
+You may defer your decision by setting your tracker up with the anydbm
+backend (which is guaranteed to be available) and switching to one of the
+other backends at any time using the instructions in the `administration
+guide`_.
Configure a Web Interface
3. `Zope product - ZRoundup`_
You may need to give the web server user permission to access the tracker home
-- see the `shared environment steps`_ for information. You may also need to
+- see the `UNIX environment steps`_ for information. You may also need to
configure your system in some way - see `platform-specific notes`_.
On windows, you would set up the command using the windows scheduler.
+As a regular job using an IMAP source
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Shared Environment Steps
-------------------------
+To retrieve from an IMAP mailbox, use a *cron* entry similar to the
+POP one::
+
+ 0,10,20,30,40,50 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support imap <imap_spec>
+
+where imap_spec is "``username:password@server``" that specifies the roundup
+submission user's IMAP account name, password and server. You may
+optionally include a mailbox to use other than the default ``INBOX`` with
+"``imap username:password@server mailbox``".
+
+If you have a secure (ie. HTTPS) IMAP server then you may use ``imaps``
+in place of ``imap`` in the command to use a secure connection.
+
+As with the POP job, on windows, you would set up the command using the
+windows scheduler.
+
+
+UNIX Environment Steps
+----------------------
Each tracker ideally should have its own UNIX group, so create
a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
may actually login and play with the roundup setup.
+Additional Language Codecs
+--------------------------
+
+If you intend to send messages to Roundup that use Chinese, Japanese or
+Korean encodings the you'll need to obtain CJKCodecs from
+http://cjkpython.berlios.de/
+
+
+
Maintenance
===========
-Read the separate `maintenance documentation`_ for information about how to
+Read the separate `administration guide`_ for information about how to
perform common maintenance tasks with Roundup.
addresses, databases to back up, etc.
1. Do you want a tracker per product you sell/support? You can just add
- a new property to your issues called Product, and filter by that.
+ a new property to your issues called Product, and filter by that. See
+ the customisation example `adding a new field to the classic schema`_.
2. Do you want to track internal software development issues and customer
- support issues separately? You can just set up an additiona "issue"
+ support issues separately? You can just set up an additional "issue"
class called "cust_issues" in the same tracker, mimicing the normal
- "issue" class, but with different properties.
+ "issue" class, but with different properties. See the customisation
+ example `tracking different types of issues`_.
Platform-Specific Notes
Linux
-----
-Make sure you read the instructions under `shared environment steps`_.
+Make sure you read the instructions under `UNIX environment steps`_.
Python 2.1.1 as shipped with SuSE7.3 might be missing module
``_weakref``.
You'll need to build Python.
-Make sure you read the instructions under `shared environment steps`_.
+Make sure you read the instructions under `UNIX environment steps`_.
+
-------------------------------------------------------------------------------
.. _`roundup specification`: spec.html
.. _`tracker configuration`: customizing.html#tracker-configuration
.. _`customisation documentation`: customizing.html
+.. _`Adding a new field to the classic schema`:
+ customizing.html#adding-a-new-field-to-the-classic-schema
+.. _`Tracking different types of issues`:
+ customizing.html#tracking-different-types-of-issues
.. _`customising roundup`: customizing.html
.. _`upgrading document`: upgrading.html
-.. _`maintenance documentation`: maintenance.html
+.. _`administration guide`: admin_guide.html
.. _sqlite: http://www.hwaci.com/sw/sqlite/
.. _metakit: http://www.equi4.com/metakit/
+.. _Psycopg: http://initd.org/software/initd/psycopg
+.. _MySQLdb: http://sourceforge.net/projects/mysql-python