7 Installation of the GIFFT tool

It is necessary to verify that the prerequisite have been correctly installed before trying to install the tool. (Cf. § "3 Prerequisite to use GIFFT ?").

The installation of GIFFT allows the user to :

The software is only installed once and for all on a server. The configuration files can always be modified afterwards according to the needs.

The installation of GIFFT is made of the following steps:

Each setup window contains a validation button. Once you have modified the values, you have to click on this button for the changes to be taken into account.

      7.1 Creating Base directories

The software needs to work in several different directories :

In this directory we will put three subdirectories:

These subdirectories can be created by GIFFT itself, so they do not need to be prepared.

 

Once these directories have been identified, and created if necessary, proceed to the next step of installation.

Warning : Please note that all these directories should belong to the "www" user, and if not, you have to make sure that he has the right to read and write in these directories.

      7.2 Placing the GIFFT files

The package in which GIFFT comes contains four main directories:

The content of "bin" goes in the cgi-bin directory. It contains GIFFT itself, and a tool used to import data from older versions of GIFFT V1. These files are executables, so they should have the appropriate properties.

The content of config is an example of configuration files, that could be copied to the config directory, but it is not really needed.

The content of images has to be copied into the images subdirectory of the server.

The content of the help directory should be copied into the help subdirectory of the server if you intend to use on-line help.

Warning : Please note that all these files should belong to the "www" user, and if not, you have to make sure that he has the right to read and write on these files.

      7.3 Configuring the web server

      There are many different kind of web servers on the market. This chapter just gives you two examples which you canuse to configure your own server:

      First you have to choose a directory where you will put all your web related documents, for example /home/web. Let's call this directory WWW.

        7.3.1 W3C httpd server

        When installing the server you have to find the httpd.conf configuration file in the directory w3c_httpd-RUN/opt/w3c_httpd/server_root/config and make sure it contains the two following lines:

        Exec /cgi-bin/* <WWW>/cgi-bin/*

        Pass /* <WWW>/www/*

        This second line tell that when you connect to your web server your documents (including GIFFT image files) will have to somewhere under the <WWW>/www directory.

        In general, the server is started as root, and changes identity as soon as it has to handle a request. This is configured the configuration file by putting the following lines:

        UserId www
        GroupId sys

        7.3.2 Apache Web Server

      When installing the server you have to find the httpd.conf configuration file in the directory /home/apache/etc. This file should contain the following line :

      DocumentRoot "/opt/apache/lib/htdocs"

      This corresponds to the WWW directory. Now there should be two lines giving the identity the server should use when executing commands :

      User www

      Group www

      And finally, the following entries defining the permissions for using web pages and executables :

      <Directory "/opt/apache/lib/htdocs">

      Options Indexes FollowSymLinks MultiViews

      AllowOverride None

      Order allow,deny

      Allow from all

      </Directory>

      ScriptAlias /cgi-bin/ "/opt/apache/lib/cgi-bin/"

       

      <Directory "/opt/apache/lib/cgi-bin">

      AllowOverride None

      Options None

      Order allow,deny

      Allow from all

      </Directory>

      7.4 Security

      Since most web servers can restrict the use of certain pages to some users providing passwords, the security has not been a concern during the development of GIFFT. Please refer to the documentation of your web server to see how you can restrict access to your local installation of GIFFT if you wish to do so.

      As an example, the following chapter explains how to configure an Apache web server to restrict access to GIFFT.

        7.4.1 Apache Web Server on Linux

      In this example we used a different directory than the usual cgi-bin to hold the binaries. To restrict access to this directory, we used the .htaccess file in the directory itself.

      So that the server accepts to handle the contents of the .htaccess file you need to change the access.conf file (usually in /etc/httpd). Normally there should be a section dealing with the directory that you are aiming at. You need to change the AllowOverride directive:

      <Directory /home/httpd/html>

      AllowOverride ALL

      </Directory>

      Then you add the following lines in the .htaccess file in the directory where you have your binary, after having inserted a real file name for the passwords:

      Options ExecCGI

      AddHandler cgi-script .cgi

      order deny,allow

      allow from all

      AuthType basic

      AuthName GIFFT

      AuthUserFile <password file full name>

      require valid-user

      Apache security tips say that you should not put the password file in the same directory as the one it protects.

      The contents of the password file can be populated using the htpasswd utility:

      % /usr/sbin/htpasswd -h

      Usage: htpasswd [-c] passwordfile username

      The -c flag creates a new file.

       

       

      7.5 Setup configuration files

There are several configuration files, and they are all in the config directory. They are only modified by the person in charge of configuring GIFFT.

Examples of these files can be found in le § "10 Annex 1 : Configuration Files Examples".

There are several ways to customize GIFFT :

        7.5.1 Setup Wizard

        When GIFFT is started for the very first time on any new installation, it detects the first installation, and starts the wizard automatically.

        The wizard starts by asking a few questions on directories. It is the same set of questions as for the setup of the main configuration file (see 7.5.2 Setup GIFFT).

        After you have answered the questions, GIFFT tries to install itself into the directories you have specified. You will see the result of that installation, with the list of items done, and the result of each. If an action has failed, you should see a red error message, with the appropriate error number which should help you to find out why the operation failed. You should then correct the problem and reload the same page until all the results are green.

        Once you have passed this first step, the wizard will go through all the configuration files in case you would like to change any of the default values. If at that moment you are not quite sure what these values could be don't worry, you can always come back later to the setup for customisation.

        7.5.2 Setup GIFFT

This is the main setup window, and therefore the most important. This step deals with the contents of the file "gifft.cfg". The contents of this file is the following:

        7.5.3 Setup Projects

The list of projects is a table with four columns. Each line corresponds to a different project. The contents of the four columns is the following :

For each project you should fill in these fields. The second and fourth field are optional, but be careful not to leave more than one project without a prefix because the names would be misleading.

The project table is saved in the "project.cfg" file.

        7.5.4 Setup Sub-Projects

The list of subprojects depends on the list of projects. To each project belongs a list of subprojects. Therefore, there are as many tables as there are projects. Each table has two columns containing :

Each table is saved into a different file. Each file name starts with the name of the project. The file name looks like this : "<project>_subproject.cfg" .

        7.5.5 Setup Modules

        The list of modules depends on the list of projects. To each project belongs a list of modules. Therefore, there are as many lists as there are projects.

        Each list is saved into a different file. Each file name starts with the name of the project. The file name looks like this : "<project>_program.cfg" .

        7.5.6 Setup Users

The list of users depends on the list of projects. To each project belongs a list of users. Therefore, there are as many tables as there are projects. Each table has two columns containing :

Each user can have several mail addresses. In this case, the addresses are separated by commas.

Each table is saved into a different file. Each file name starts with the name of the project. The file name looks like this : "<project>_user.cfg" .

        7.5.7 Setup Versions and Deadlines

        The list of versions and deadlines depends on the list of projects. To each project belongs a list of versions and deadlines. Therefore, there are as many tables as there are projects.

        There is a list for the versions and there is a list for deadlines. These tables are independent, and for each delivery it is a good idea to update the version file.

        Each table is saved into a different file. Each file name starts with the name of the project. The version file name looks like this : "<project>_version.cfg" . The deadline file name looks like this : "<project>_deadline.cfg" .

        7.5.8 Setup Phases

The list of phases is a table with two columns. Each line corresponds to a different phase. The contents of the two columns is the following :

The prefix can only be one character.

The phase file name looks like this : "phases.cfg" .

        7.5.9 Setup Impacts

        The list of impacts represents the list of possible impacts of bug on the product.

        The impact file name looks like this : "impacts.cfg" .

        7.5.10 Setup Send-Mail Policy

The mail sending policy help you to configure when and to whom will an e-mail be sent. Each line corresponds to all the different actions, all the possible events that can happen to a fact sheet. These events would be :

All these actions can generate e-mails which can be sent to

To let GIFFT send an e-mail to a destination you have to check the box in the right column and line.

The impact file name looks like this : "sendmail.cfg" .

      7.6 Import old version data

The GIFFT package contains a tool for importing data from former version 1.0 of GIFFT. To import the data, the configuration files have to be properly set up, in order to reception the incoming files.

The tool is a command-line interface, with the following syntax :

import <project> <directory>

where

Caution : some operating systems already have an included import command, make sure you are using the right executable.

Versions from 2.0 onward are fully backward compatible with older versions unless otherwise indicated. Even then, the installation phase would provide steps to upgrade the database.

      7.7 Frequent installation problems

      Some frequent installation problems are listed below. If you have a problem installing GIIFT, please try to see if your problem is one of them. If not, you can contact your support line as indicated in chapter {2.5 Who to contact ?}.

        7.7.1 Installation Wizard page keeps coming back

When the program starts, it tries to find the file $PWD/config/gift.cfg .

It can happen that the variable $PWD is not set, or that it is set, but is empty. In that case, the server looks in the current directory to see if it finds a configuration directory (config). The problem is to find out which is the current directory for the web server. Usually, it is either the same directory where the executable gifft.cgi is found, or the top of the root directory (/).

The source of the first Wizard page contains a comment telling you which file it is trying to reach, so you can have a clue on what it is trying to do.

Experience shows that this problem only happens on unix/linux systems. On Windows systems the configuration directory is right next to the gift.cgi executable.

If this problem occurs, you have several solutions:

        7.7.2 After clicking "next" on first Wizard page, you get an error

When you click on the next button, the program tries to create the directories you have indicated in the first page, and the configuration directory directly in the next to the gifft.cgi executable.

If this problem occurs, please verify the following :

        7.7.3 No mails are sent

        Please verify that the host you indicated as mail server accepts a telnet connection on port 25.

        7.7.4 Can not create new bug reports because the deadline list is empty

        The list of deadlines needs to have version numbers that have not been delivered yet, and that are therefore different than the list of versions (<Project>_version.cfg) which is the file you update each time you build a new version.

        All versions that are present both in the deadline and in the versions list, will not be displayed in the deadline list because a deadline can not be a version that has already been delivered.

        7.7.5 Images are not displayed

You can configure the path to the image files in the setup. The directory you type needs to be a relative path starting from the top directory of all your HTML files. This is because the images files are handled by the web server, and for security reasons it is not allowed to reach any other part of your directory tree.