Gnatsweb Web interface to GNATS The GNU Problem Report Management System Installation Guide for Gnatsweb 4 Quick start for the impatient ============================= 1. The following procedure assumes that you have a working installation of GNATS version 4. If not, refer to the installation instructions in Chapter 3, `Installing GNATS' of the GNATS manual. PLEASE NOTE: Gnatsweb 4 does not work with GNATS 3.x servers. It only supports GNATS 4.0 or newer. If you are upgrading from an old Gnatsweb 4 installation, see the notice about upgrading under item 6 below. If you are migrating to GNATS 4 from GNATS 3.x and are upgrading from an old Gnatsweb 2.x installation, you should back up and remove the Gnatsweb files in your cgi-bin directory before proceeding. 2. Since Gnatsweb runs on your web server, you need to grant the web server access to the GNATS database. Here are two different ways to accomplish this: a. Grant 'edit' access to the web server in the gnatsd.host_access file. This file is located in /usr/local/etc/gnats by default, but this may have been overridden when GNATS was installed. Typically, the web server is running on the same machine as the GNATS server, so that the following line needs to be added to gnatsd.host_access: localhost:edit: Do note that this disables all security -- anyone with access to the Gnatsweb script on the web server gets edit access to your GNATS databases. Gnatsweb will still prompt for a username at login, but this username will only be used for generating Audit-Trail entries to track PR edits. This means that you don't need to maintain a GNATS user database since any login name is accepted. b. Grant restricted access only to the web server in the gnatsd.host_access file. Grant higher access to individual users by adding username/password entries in the gnats-adm/gnatsd.access file or the global gnatsd.access file by default located in /usr/local/etc/gnats. The web server must have at least 'listdb' access. If the web server is running on the same machine as the GNATS server, the following line needs to be added to gnatsd.host_access: localhost:listdb: 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. For more information about GNATS access control, see Appendix C, `Controlling access to databases' of the GNATS 4 manual. 3. If your GNATS server is on the same host as your web server, skip this step for now. If not, edit 'gnatsweb-site.pl', the site configuration file. You need to set the variables $site_gnats_host and $site_gnats_port to point to your GNATS server. Default installations of GNATS run on port 1529, so if you have a default GNATS installation running on the host `gnats.example.com', you would set $site_gnats_host to 'gnats.example.com' and $site_gnats_port to '1529'. 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=user PASSWORD=password DATABASE=database where 'user' is the name of a user defined in your GNATS server's gnatsd.access files, 'password' is the user's password and 'database' is the name of one of the databases on your server. 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 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 NOTICE TO UPGRADERS: If your cgi-bin directory already contains the files gnatsweb.pl and gnatsweb.html, these will be renamed to gnatsweb.pl.old and gnatsweb-site.html.old before the new files are installed. If you already have a gnatsweb-site.pl file, this file will not be touched during installation. However, you should compare the gnatsweb-site.pl in the distribution with the currently installed file and make sure that there isn't any new stuff which you need to copy into your installed configuration. How to proceed ============== You should now have a basic, working Gnatsweb installation. To tailor it further to your site's needs, go on to read the CUSTOMIZE document. 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.