~~NOTOC~~




====== GNATS issue tracking system configuration howto ======

GNATS is an issue tracking system that has important advantages when compared to other alternatives. This howto is a simple step by step guide for setting-up and using the GNATS issue tracker.




===== Advantages of GNATS =====

The advantage of GNATS over several other issue tracking system are : (1) GNATS offers client/server interface through the //gnatsd,send-pr,query-pr,edit-pr// these allow the interaction with GNATS database from the command line which is great. (2) GNATS allows 'relocation' of issues or bugs and moving them freely between categories/modules. If in a hurry, the user can just post an issue to an un-undefined category. GNATS will associate the default 'pending' category to the new issue until the administrator or the user himself assigns the correct category to the new issue. (3) GNATS uses a file-based back-end database which makes it easy to backup and.


===== Installing GNATS =====

GNATS can be installed through packages system in most linux/unix systems. Under FreeBSD using the ports collection, you can install gnats and gnats web as follows 

<code>
cd /usr/ports/databases/gnats4
make install
cd /usr/ports/databases/gnatsweb4
make install
</code>

The installation will add a user //gnats// in the system. All the files used by the GNATS system must be owned by the //gnats// user.

===== Setting up the gnatsd server =====

==== Update /etc/aliases ====

Add the following 

<code>
gnats-admin:  address
bugs:  "| /usr/local/libexec/gnats/queue-pr -q"
</code>

Then run

<code>
newaliases
</code>

===== Update /etc/inetd.conf =====

Add the following 

<code>

  support	stream	tcp	nowait	gnats	/usr/local/libexec/gnats/gnatsdgnatsd

</code>

Then restart inetd as follows

<code>
/etc/rc.d/inetd restart
</code>

==== Add a new cron-job for the gnats user ====

As root type 

<code>
crontab -u gnats -e
0,10,20,30,40,50 * * * * /usr/local/libexec/gnats/queue-pr --run
</code>

===== Adding databases =====

To add a database, the following steps are required :

==== Edit /usr/local/etc/gnats/databases ====
Add an entry as follows :

<code>
databasename:Bug database:/var/db/gnats/databasename
</code>


==== Create the database ====

<code> 
/usr/local/libexec/gnats/mkdb databasename
</code>


==== Configuring access privileges ====
 
//Host based access control ://\\
Edit **/var/db/gnats/databasename/gnats-adm/gnatsd.host_access**, and add lines such as 

<code>
   localhost:edit:
   156.54.55.*:view:
</code>

//User based access control : //\\ 
Edit **/var/db/gnats/databasename/gnats-adm/gnatsd.user_access**,  and add lines such as 

<code>
   joe:$0$joepassword:admin
   bill:$0$billpassword:edit
</code>



==== Configuring categories and responsibles ====

//Add a new category or module : //\\
Edit the file **/var/db/gnats/databasename/gnats-adm/categories**, and add a line such as 

<code>
  modulename:Some Project or Module:joe:
</code>

Where joe is a responsible.

//Add responsibles: //\\
Edit **/var/db/gnats/databasename/gnats-adm/responsibles**, and add a line such as 

<code>
joe:Joe Foe:joe
bill:Mister Bill:bill@example.com
</code>

//Add submitters: //\\
Edit **/var/db/gnats/databasename/gnats-adm/submitters**, and add a line such as 

<code>
dod:Department of Defense:DARPA:4:bill:al
</code>



===== Using and administrating GNATS =====


==== Accessing GNATS databases using gnatsweb ====

The gnatsweb will install cgi scripts in the default cgi-bin directory (/usr/local/www/cgi-bin). Edit the gnatsweb.pl file to customize some variables, then put these files in a location where they can be accessed and executed as cg-scripts. You can access the GNATS database using the web interface by pointing the browser to the gnatsweb.pl script (e.g. http://www.example.com/cgi-bin/gnatsweb).


==== Using the client/server interface ====

To use the GNATS system from remote locations, the users can access databases through the web interface or using the client/server interface. The latter alternative requires installing client side scripts. Under Debian/Ubuntu, you can do this by issuing the following command :

<code>
apt-get install gnats-user
</code>

The programs //send-pr,query-pr,edit-pr// will all be installed. To use them, it is preferable that the environment variable GNATSDB points to the GNATS database. Set it as follows (assuming bash shell)

<code>
export GNATSDB=gnatsserver:1529:database:login:pass
</code>

Now the user can access the database using the client tools. The following is a list of examples

^Command^Description^
|query-pr -q| List summary of all issues |
|query-pr --list-fields| List all fields |
|query-pr --valid-values class| List all classes/projects |
|query-pr --category somecategory | Lists all issues in the category //somecategory//|
|edit-pr 2| Edits issue number 2|
|send-pr|Presents the user with fields to fill in and creates a new issue report based on the provided information|

See the manuals  of send-pr,query-pr and edit-pr to get more information.


===== Administrating a GNATS system =====

http://www.cs.utah.edu/dept/old/texinfo/gnats/gnats_3.html#SEC33

{{tag>services unix project-management}}


~~DISCUSSION~~