gnats2w can be configured basically by setting the variables in the `config.py' file. This defines basic installation directories, e-mails, URLs, GNATS database, some Web forms element appearance, etc. User specific customization can be achieved through environment variables, which can be set by the Web server with respect to an URL, from which a CGI script was invoked.
Special care is applied to access rights. gnats2w allows you to define fine control about who can access the bug database and who can modify it, allowing any authentization method you can use in Python.
Finally, gnats2w has FCGI support to reduce overhead caused by Python startup times. With a bit of configuration, you can avoid this overhead.
The main configuration place is the file `config.py'. It consists mainly of configuration variables, which you should set according to your local installation and your local requirements. Primarily URLs and paths are set here.
The file contains configuration variables and their values separated by
the `=' operator. This is standard Python module file but do not
worry if you do not know Python. All special you need to know is that
strings are enclosed in apostrophes or double quotes and that None
is something like nil
in Lisp or NULL
in C.
You must set all the variables here to values specific to your site and gnats2w installation.
Directory paths:
GNATS_PRG_DIR
TEMPLATE_DIR
DICTIONARY_DIR
URLs:
HOST_URL
BASE_URL
HOST_URL
and the `index.html'
paths.
Mailing:
MAIL
ADMIN_MAIL
The following configuration variables specify your database setup.
GNATS_DIR
SITE
DEFAULT_CATEGORY
AUTO_CONFIDENTIAL
0
,
there is nothing special about confidentiality. If it is 1
, new
reports can be set confidential,
See section `Problem Report fields' in The GNATS manual,
automatically for some categories. Such auto-confidential categories
are denoted by the *
character at the very beginning of their
category description in the `categories' file, the second field,
See section `categories file' in The GNATS manual.
(1)
One important thing in bug hunting is to allow users accessing a bug tracking system in their own language. gnats2w has some support for message translations. (2) gnats2w consideres language codes given by the Web browser to it and selects appropriate available message catalog and HTML templates.
The default language is English. If you want to support another
language, you need translated `*.dtml' files and a message catalog.
Translated `*.dtml' files have an additional extension, which is
the ISO language code, e.g. Czech document templates have the extension
`*.dtml.cs'. Message catalogs have names equal to the language
code and are placed in the directory defined by the variable
DICTIONARY_DIR
, See section Installation specific configuration.
Additionally, you can have your own catalogs in the directory defined by
the variable DICTIONARY_DIR_LOCAL
(see below) for new messages
appearing in your own extension code.
The format of message catalog files is as follows:
dictionary = { 'English message 1': 'translation 1', 'English message 2': 'translation 2', 'English message 3': 'translation 3', ... 'English message N': 'translation N' }
I.e. it contains Python variable dictionary
, which is an
associative array with English messages as keys and their translations
as values.
The following configuration variables has some relation to the translations:
LANGUAGE
"
).
DICTIONARY_DIR_LOCAL
The main index page has a part left for local text. For example, you can put links to various category selections here, See section Environment variables.
If the variable LOCAL_INDEX_FUNCTION
is None
, the local part
is left empty. Otherwise LOCAL_INDEX_FUNCTION
should be set to a
Python function generating an HTML 3.2 code, which will be put to the
local part of the main index page. The function takes no arguments, but
can access global objects, See section Internals.
There are also some visibility flags, which allow you to hide some
information not interesting to your users. All the following variables
can have the value 0
(not visible) or 1
(visible):
DISPLAY_CONFIDENTIAL
DISPLAY_ORGANIZATION
DISPLAY_IDREQUEST
If the directory with CGI scripts contains a file named `config', all settings in this file take precedence over the ones in `config.py'. This way you can have different configurations for different URLs -- just make symbolink links to all the CGI scripts in another directory and override the options with `config' file in the new directory.
One obvious application of this feature is to allow access to different
GNATS databases through different URLs by setting the variable
GNATS_DIR
, See section Database specific configuration, in different
`config' files.
Not everything can be set in a static configuration file. For example, user preferences are difficult to store there. To make such problems easier, gnats2w can be customized also by environment variables. Then you can with enough powerful Web servers (like Apache) customize gnats2w e.g. through URL paths to gnats2w scripts. For example, Apache rewrite rules allow you to set the environment variables based on URL, while rewriting the URL into some canonical form.
There are considered two such environment variables:
GNATS_EXPERT_MODE
'on'
, the helps are reduced.
GNATS_CATEGORIZE
GNATS_CATEGORIZE
is an empty string
("
), all accessible categories are visible.
@FIXME{}
By default, gnats2w allows access everyone to everything. This is often not what you would like to have. So gnats2w is equipped with some support for access regulation and authentization. The authorization and authentization basic gnats2w principles are described below.
The module `access.py' defines some basic Python classes, of which
you can compose your own access customization classes. If you want to
change the default behavior, create new access class and assign it to
the configuration variable ACCESS
, See section Basic configuration.
Access rights are divided into three categories:
For each of this category, the basic rights can be:
The abstract class Access
defines appropriate constants for all
these categories: Access.SUBMIT
, Access.VIEW
,
Access.EDIT
, Access.DENIED
, Access.RESTRICTED
,
Access.FULL
.
Identification of the accessor is composed from the three parts:
The following authentization classes are predefined:
Email_Identity
HTTPS
You can assign whatever subclass of the Access
class you define.
One useful predefined subclass of the Access
class is
Enumeration
. The following text describes its usage.
Access is defined by a dictionary with keys as users' identities and values defining access for a user with a given identity. If the dictionary contains an item with an empty string as a key, it defines default access. If there is no such an item, access is denied for accessors not presented in the dictionary.
Values are sequences of triples (ACCESS, RESTRICTED_ALLOWED, SPECIAL), where the items mean:
Access
class constants SUBMIT
, VIEW
, or
EDIT
.
Enumerated
class constants RESPONSIBLE
(allow
access only for the responsible), ORIGINATOR
(allow access only
for the originator), RELATED
(allow access only for the
responsible or the originator); or None
(allow access for all).
For a given key, several triples can be defined in its value sequence, with the same of different elements. The most liberal triple for a particular kind of access is considered.
The dictionary described above is simply given as the only argument of
the Enumeration
constructor. The Enumeration
instance is
assigned to the ACCESS
configuration variable.
The simplest thing you can do is to allow access anyone to everything:
from gnats2w.access import Access ACCESS = Access ()
Let us look at more complicated example:
from gnats2w.access import Enumeration MY_ACCESS = {'administrator': ((Access.SUBMIT, 1, None), (Access.EDIT, 1, None), (Access.VIEW, 1, None)), 'certificate': ((Access.SUBMIT, 1, None), (Access.EDIT, 1, Access.RELATED), (Access.VIEW, 1, None)), '': ((Access.SUBMIT, 0, None), (Access.EDIT, 0, Access.RELATED), (Access.VIEW, 0, None))} ACCESS = Enumeration (MY_ACCESS)
This configuration has the following features:
certificate
.
administrator
can do everything with
the problems.
To let it work reasonably, there has to be defined mapping on the user
identifications certificate
and administrator
. This can
be achieved e.g. in the following way:
from gnats2w import access class My_Enumeration (Enumeration, access.HTTPS): def identity (self): name = self.name () if name == 'John Powerful': return 'administrator' elif name: return 'certificate' else: return '' ACCESS = My_Enumeration (MY_ACCESS)
To avoid slow Python startups of CGI scripts, gnats2w provides an interface to FastCGI. To use gnats2w with FastCGI, you need have installed the module `fcgi.py'. You can find it at http://www.fastcgi.com.
After this, setup your Web server appropriately to get FastCGI support and you can run gnats2w through the `fcgiscripts.py' module and symbolic links made to it.
Go to the first, previous, next, last section, table of contents.