
                   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.

    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.

       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


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.

    2. Problem: I just submitted a PR specifying my email address.  The
       next time I go to submit a PR, shouldn't the email address
       already be filled in?

       Solution: Yes, it should.  Upgrade your version of CGI.pm to
       2.50, available from http://stein.cshl.org/WWW/software/CGI/
       I know that 2.42 sometimes does not work, and 2.50 does.
