
                   Gnatsweb - web front-end to gnats

                           Installation Guide


Quick start for the impatient
=============================

    1. Install gnatsd, the gnats network server.  Gnatsweb doesn't run
       without it.

    2. Configure gnatsd to allow host access to your web server.  Here
       are two different ways to accomplish this:

       a. Grant 'edit' access the web server in the
          gnats-adm/gnatsd.conf file, thus giving everyone with access
          to the web server edit access to your Gnats database.
          Gnatsweb will still prompt for a username/password; this
          username will be used for the Audit-Trail, but you don't need
          to put the username into the gnats-adm/gnatsd.access file.

       b. Grant restricted access only (such as 'view' or 'none') to the
          web server in the gnats-adm/gnatsd.conf file.  Grant higher
          access to individual users by adding username/password entries
          in the gnats-adm/gnatsd.access file.

       If you want more restrictions than provided by those solutions,
       consider restricting access to your web server, or the particular
       CGI directory where you plan to install gnatsweb.

    3. If your gnats server is on the same host as your web server,
       skip this step.  If not, create 'gnatsweb-site.pl', the site
       configuration file.  Read gnatsweb.pl, and follow the directions.
       Basic configuration requires only that you specify the host +
       port number of your gnats server.

    4. Change line 1 of gnatsweb.pl to point to the location of your
       'perl' executable.  Perl must be version 5.

    5. Run the tests to make sure the setup is OK.  Specify a
       username/password/database_name on the command line like so:

           make test USERNAME=anon PASSWORD=pw DATABASE=db_alias

       Note: no PR's are modified during the tests.  The database alias,
       username and password must be valid, and the database must contain
       at least one PR.

       Note: if 'perl' for you is not Perl 5, then 'make PERL=/path/perl5'

       If you don't see the message "All tests passed", investigate.

    6. Install gnatsweb.pl (and gnatsweb-site.pl if you created one)
       into a CGI-enabled directory on your web server.  For example, on
       Red Hat Linux with Apache:

           make install CGI_DIR=/home/httpd/cgi-bin

    7. Install the MIME::Base64 package, if you want to use file
       attachments in your PR's with gnatsweb.  The easiest way to do this
       is to type (as root if the perl installation is owned by root):

           perl -MCPAN -e 'install MIME::Base64'


Known problems and solutions
============================

    1. Problem: Email is going to the wrong place, e.g. to 'joe' instead
       of 'joe@my.org'.

       Solution: Fix all the email addresses in
       $GNATS_ROOT/gnats-adm/responsible.
