
                   Gnatsweb - web front-end to GNATS

                           Installation Guide


Steps to install Gnatsweb on your web server
============================================

    1. Make sure you have a working GNATS installation with a
       non-empty database before installing Gnatsweb.

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

       a. Grant 'edit' access to 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.

          If you are running the web server on the same machine as
          GNATS is running on, the following entry in gnatsd.conf will
          give edit access:

            localhost:edit:

       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.

          NOTE: If you have multiple databases in your GNATS setup,
          Gnatsweb will not work properly if you set access for the
          web server to 'none', because this will prevent Gnatsweb
          from obtaining a list of what databases are actually
          available on the server. In this case, you must set access
          to 'view' or higher.  This is a deficiency which will
          hopefully be adressed in coming versions of GNATS.

          If you are running the web server on the same machine as
          GNATS is running on, one of the following entries in
          gnatsd.conf will give the required access:

            localhost:view:

          or

            localhost:none:

       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. In order for Gnatsweb to work properly, you need to install two
       Perl modules on your system.  Some systems may already have
       them installed, but the following procedure ensures that you
       have the correct versions of them on your system:

       CGI.pm v2.56 or newer (the unofficial version 3.x of CGI.pm
       will not work): Gnatsweb will not work at all without this
       module.  On most systems, the following command (run as root)
       installs the correct version:

       perl -MCPAN -e 'install CGI'

       MIME::BASE64 (Gnatsweb will run without it, but attachment
       handling will be disabled).  Most systems get the right version
       when the following command is run (as root):

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

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

    6. 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=dbalias

       Before you run this test, you need to set up a file
       /etc/gnats-db.conf, containing a list of databases on your
       server, and their alias names.  The GNATS manual is
       unfortunately not clear about this, but even if you have only a
       single database on your machine, you need a gnats-db.conf file.
       Read appendix C of the GNATS manual, entitled "Multiple
       Databases on one host" for more information on the format of
       this file.  Again, the information in appendix C applies even
       if you have only a single database.

       The dbalias value in the make test command line should be one
       of the alias names defined in gnats-db.conf.

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

       If you don't see the message "All tests passed", investigate.
       The TROUBLESHOOTING document distributed with Gnatsweb contains
       some useful advice.  See also the end of this document.

    7. Install gnatsweb.pl (and gnatsweb-site.pl if you created one)
       into a CGI-enabled directory on your web server.  For a typical
       Apache web server installation:

         make install CGI_DIR=/usr/local/apache/cgi-bin


What to do if you have problems
===============================

- Go through the TROUBLESHOOTING document.
- Try sifting through the GNATS-related mailing list archives at
  http://savannah.gnu.org/mail/?group_id=65
- If you still have problems, try posting to the help-gnats mailing
  list.  Subscribe from http://savannah.gnu.org/mail/?group_id=65
  Please avoid posting until you are completely certain that there is
  nothing relevant in the mailinglist archives.
