![[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
==================
Installing Roundup
==================
-:Version: $Revision: 1.14 $
+:Version: $Revision: 1.23 $
.. contents::
.. contents::
These include the email gateway, the roundup
HTTP server, the roundup administration command-line interface, etc.
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.
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
"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
Prerequisites
later. Download the latest version from http://pybsddb.sourceforge.net/.
later. Download the latest version from http://pybsddb.sourceforge.net/.
+Getting Roundup
+===============
+
+Download the latest version from http://roundup.sf.net/.
+
Testing your Python
-------------------
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.
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
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::
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
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
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):
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:
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
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_::
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
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
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``
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:
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::
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'
If you use Sendmail's ``smrsh`` mechanism, please read the notes
under 'Platform-Specific Notes'
line)::
10 * * * * /opt/roundup/bin/roundup-mailgw
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
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
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.
released.
Install roundup as usual (see installation_).
ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
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.
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
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
Further Reading
which points to the full path of your actual ``roundup-mailgw``
script.
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
Linux