![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/installation.txt b/doc/installation.txt
index 374f829758792d82f4ff4ab809c8d1497f2d8f4b..a39595cdeadd38877ed0f044a84843eee08ecc00 100644 (file)
--- a/doc/installation.txt
+++ b/doc/installation.txt
Installing Roundup
==================
-:Version: $Revision: 1.14 $
+:Version: $Revision: 1.23 $
.. contents::
These include the email gateway, the roundup
HTTP server, the roundup administration command-line interface, etc.
-Roundup instances
- Instances consist of core support files, issues
- (be they bug reports or otherwise), instance configuration file(s),
- etc. Roundup instances also adhere to a specific "Template" which
+Roundup trackers
+ Trackers consist of core support files, issues
+ (be they bug reports or otherwise), tracker configuration file(s),
+ etc. Roundup trackers also adhere to a specific "Template" which
defines the fields usable/assignable on a per-issue basis. A
description of the provided templates follows.
"usability" and "feature".
Users of this template will want to change the contents of the product
-class as soon as the instance is created.
+class as soon as the tracker is created.
Prerequisites
later. Download the latest version from http://pybsddb.sourceforge.net/.
+Getting Roundup
+===============
+
+Download the latest version from http://roundup.sf.net/.
+
Testing your Python
-------------------
-Run ``python ./run_tests`` and make sure there
-are no errors. If there are errors, please let us know!
+Once you've unpacked roundup's source, run ``python ./run_tests`` in the
+source directory and make sure there are no errors.
+If there are errors, please let us know!
If the above fails, you may be using the wrong version of python. Try
``python2 ./run_tests``. If that works, you will need to substitute
``python2`` for ``python`` in all further commands you use in relation to
Roundup -- from installation and scripts.
-Getting Roundup
-===============
-
-Download the latest version from http://roundup.sf.net/.
-
Installation
============
Set aside 15-30 minutes. Please make sure you're using a supported version of
-Python -- see `testing your python`_.
+Python -- see `testing your python`_. There's three sections to this
+installation guide:
+
+1. `basic installation steps`_ that all installers must follow
+2. `shared environment steps`_ to take if you're installing on a shared
+ UNIX machine and want to restrict local access to roundup
+3. `internet setup`_ steps to take if your tracker is to be used by the wider
+ internet community
+
+Most users will only need to follow the first step, since the environment will
+be a trusted one.
+
+
+Basic Installation Steps
+------------------------
1. To install the Roundup support code into your Python tree and
Roundup scripts into /usr/local/bin::
python setup.py install
If you would like to place the Roundup scripts in a directory other
- than ``/usr/local/bin``, use the ``--install-scripts`` option as follows,
- replacing ``/opt/roundup/bin`` with the location where you would like
- the scripts to reside::
+ than ``/usr/local/bin``, then specify the preferred location with
+ ``--install-script``. For example, to install them in
+ ``/opt/roundup/bin``::
python setup.py install --install-scripts=/opt/roundup/bin
-2. To create a Roundup instance (necessary to do before you can
+2. To create a Roundup tracker (necessary to do before you can
use the software in any real fashion):
- a. (Optional) If you intend to keep your roundup instances
+ a. (Optional) If you intend to keep your roundup trackers
under one top level directory which does not exist yet,
you should create that directory now. Example:
- mkdir /opt/roundup/instances
+ mkdir /opt/roundup/trackers
b. Either add the Roundup script location to your ``PATH``
environment variable or specify the full path to
You will be asked a series of questions. A description of
the Roundup-provided templates can be found under the Overview_::
- Enter instance home: /opt/roundup/instances/support
+ Enter tracker home: /opt/roundup/trackers/support
Templates: classic, extended
Select template [classic]: classic
Back ends: anydbm, bsddb
Select backend [anydbm]: anydbm
- You will now be directed to edit the instance configuration and
+ You will now be directed to edit the tracker configuration and
initial schema. See `Customising Roundup`_ for details on configuration
- and schema changes.
+ and schema changes. Note that you may change any of the configuration
+ after you've initialised the tracker - it's just better to have valid
+ values for this stuff now.
d. ``roundup-admin initialise``
- This step initialises the instance database. You will need to supply
- an admin password at this step. You will be prompted:
+ This step initialises the tracker database. You will need to supply
+ an admin password at this step. You will be prompted::
Admin Password:
Confirm:
- Once this is done, the instance has been created.
+ Once this is done, the tracker has been created.
+
+3. XXX Set up the CGI interface
+
+4. XXX Set up the mail gateway
+
+
+Shared Environment Steps
+------------------------
-3. Each instance ideally should have its own UNIX group, so create
- a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
- you're using NIS). To continue with my examples so far, I would
- create the UNIX group 'support', although the name of the UNIX
- group does not have to be the same as the instance name. To this
- 'support' group I then add all of the UNIX usernames who will be
- working with this Roundup instance. In addition to 'real' users,
- the Roundup email gateway will need to have permissions to this
- area as well, so add the user your mail service runs as to the
- group. The UNIX group might then look like::
+Each tracker ideally should have its own UNIX group, so create
+a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
+you're using NIS). To continue with my examples so far, I would
+create the UNIX group 'support', although the name of the UNIX
+group does not have to be the same as the tracker name. To this
+'support' group I then add all of the UNIX usernames who will be
+working with this Roundup tracker. In addition to 'real' users,
+the Roundup email gateway will need to have permissions to this
+area as well, so add the user your mail service runs as to the
+group. The UNIX group might then look like::
- support:*:1002:jblaine,samh,geezer,mail
+ support:*:1002:jblaine,samh,geezer,mail
- If you intend to use the web interface (as most people do), you
- should also add the username your web server runs as to the group.
- My group now looks like this::
+If you intend to use the web interface (as most people do), you
+should also add the username your web server runs as to the group.
+My group now looks like this::
- support:*:1002:jblaine,samh,geezer,mail,apache
+ support:*:1002:jblaine,samh,geezer,mail,apache
-4. Configure your new instance by editing the file ``instance_config.py``
- located in the instance home you specified in step 2c above. This
- file is Python code and must adhere to Python syntax rules, but
- don't be daunted if you do not know Python - it should look pretty
- straightfoward if you carefully read the comments in the file.
+The tracker "db" directory should be chmod'ed g+sw so that the group can
+write to the database, and any new files created in the database will be owned
+by the group.
-5. There are two supported ways to get emailed issues into the
- Roundup instance. You should pick ONE of the following, both
+An alternative to the above is to create a new user who has the sole
+responsibility of running roundup. This user:
+
+1. runs the CGI interface daemon
+2. runs regular polls for email
+3. runs regular checks (using cron) to ensure the daemon is up
+4. optionally has no login password so that nobody but the "root" user
+ may actually login and play with the roundup setup.
+
+Internet Setup
+--------------
+
+1. There are two supported ways to get emailed issues into the
+ Roundup tracker. You should pick ONE of the following, both
of which will continue my example setup from above:
a. Set up a mail alias called "support" as::
- "|/opt/roundup/bin/roundup-mailgw /opt/roundup/instances/support"
+ "|/opt/roundup/bin/roundup-mailgw /opt/roundup/trackers/support"
If you use Sendmail's ``smrsh`` mechanism, please read the notes
under 'Platform-Specific Notes'
line)::
10 * * * * /opt/roundup/bin/roundup-mailgw
- /opt/roundup/instances/support /var/mail/support
+ /opt/roundup/trackers/support /var/mail/support
-6. TODO (mention perms)
+ If you don't want to use the email component of Roundup, then remove the
+ "``nosyreator.py``" module from your tracker "``detectors``" directory.
-7. Test the email gateway. Under most flavors of UNIX, this
+2. Test the email gateway. Under most flavors of UNIX, this
can be done by::
echo test | mail -s '[issue] test' support@YOUR_DOMAIN_HERE
+XXX mention HTTPS
+XXX mention Basic vs. cookie auth
+
Upgrading
=========
Read the separate `upgrading document`_, which describes the steps needed to
-upgrade existing tracker instances for each version of Roundup that is
+upgrade existing tracker trackers for each version of Roundup that is
released.
Install roundup as usual (see installation_).
ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
-your Products directory either in an INSTANCE_HOME/Products or the Zope
+your Products directory either in an TRACKER_HOME/Products or the Zope
code tree lib/python/Products.
-You will need to create the instance using the roundup-admin tool (step 2 in
+You will need to create the tracker using the roundup-admin tool (step 2 in
installation_).
When you next (re)start up Zope, you will be able to add a ZRoundup object
-that interfaces to your new instance.
+that interfaces to your new tracker.
Further Reading
which points to the full path of your actual ``roundup-mailgw``
script.
-2. change your alias to ``"|roundup-mailgw <instance_home>"``
+2. change your alias to ``"|roundup-mailgw <tracker_home>"``
Linux