BugTracker - Admin Guide

Software Installation and System Configuration

Overview

This chapter provides help information necessary for installation and initial configuration of the software. For information regarding customizing this software to your requirements and routine administration tasks please refer to chapters: [ Administrator's Interface | Customizing the system ] .

This software works on Windows 2000 Server, Windows 2000 Workstation, and Windows Server 2003. Software has not been tested, but should also work on Small Business Server 2003 and future products of this class. Windows 2000 Workstation has certain limitations regarding the number of users connected via web interface. If you are a large organization, consider using server class OS. This bug tracking system uses very little system resources and does not require a dedicated server. It could be cost-effective to share it with, for example, your Intranet. The same applies to SQL Server. You don't have to install a separate SQL Server software, however, the best performance and reliability achieved when both IIS and SQL Server are installed on the same physical machine, because in this setup you eliminate one extra network connection between IIS and SQL and dependency on the other machine and network appliances.

This documentation assumes that you have sufficient Administrative privileges and all configuration is done locally on the server you are configuring.

This documentation assumes that you are familiar with Windows 2000/2003 Server (OS), Internet Information Service components (IIS), Microsoft SQL Server, Microsoft Data Access Component (MDAC/ODBC) and have already installed it. IIS is included in you Windows Server OS and MDAC/ODBC is included in SQL Server and many other Microsoft products.

We recommend you to download and apply latest Service Packs and OS Updates for all of the components mentioned above prior to installation of this software. You can download it from here:

Software Installation

This bug tracking system includes two major components: the software and the database. The software component includes server-side script (.asp files), static HTML pages, JavaScript libraries, and image files. The database component consists of a single file called BugTracker.mdf

Installation of this software is a simple process of copying folders from the installation disk (or a Zip file) to the web root directory of your website. Default web root directory is set to "C:\Inetpub\wwwroot" by the IIS setup program, however if you changed this setting please make appropriate corrections when reading this chapter. The following table shows source and destination locations for all top-level folders.

Source folder

Destination folder
under your "Inetpub\wwwroot"

Contains

wwwroot\geniesys.net

\geniesys.net

Components shared among multiple modules and software packages.

\css	- Cascading Style Sheets
\lbi	- Server-side library files
\lib	- Client-side library files
\images	- Image library

wwwroot\GenieTracker

\GenieTracker

Application files, help, customer interface module.

Source file

Destination folder

Contains

MSSQL\Data\BugTracker.mdf

Either,

a) default SQL Server data directory (defined during SQL Server installation
(usually ?:\SQL Server\MSSQL\Data));

b) a user-defined local directory;

Ready-to-use bug tracker database. It contains all the tables, views, and other objects. You will still need to create user account(s) such as IUSR_<host> (see Configuring SQL Server)

DO NOT place this file on a network drive, anywhere under "Inetpub" folder or any other folder where your users or other (than SQL Server) software may access it.

MSSQL\Scripts

Do not copy

SQL scripts and data files used to build and initialize database from scratch. These scripts (except 5.1) are not required during normal installation.

Configuring Internet Information Server - Web Service

After all the files and folders are copied as described above, you can proceed to IIS Web Service configuration.

Start "Internet Services Manager" tool

Start->Programs->Administrative Tools->Internet Services Manager
OR
Control Panel ->Administrative Tools->Internet Services Manager

In the "Internet Services Manager" locate your server, locate "geniesys.net" directory. For each subdirectory listed below open its properties (right-click -> Properties) and modify it as shown.

Directories css, images

Only as a precaution, remove "Execute" permissions. These two directories contain no executable scripts anyway. Also, no need to log visits and index this resource.

Directory lbi

Only as a precaution, remove "Read" access and "Execute" permissions.This directory contains ASP library files that are used locally on the server and need not to be accessed by web users. Also, no need to log visits and index this resource.

Directory lib

Contains server-side scripts (*.asp) and non-executable clien-side scripts (*.js). Also, no need to log visits and index this resource.

For the application directory "GenieTracker".

IMPORTANT: In "Application Settings" you must create application. Click "Create" button and type a short name. This name will be a part of the URL used to access the system.
For example, name "BugTracker" will result into
http://<host>/BugTracker

Configuring SQL Server

The following instructions apply to Microsoft SQL Server Version 8.0. This document assumes that you are familiar with the administration and use of Microsoft SQL Server. Please refer to SQL Server documentation for detailed instructions when necessary. For questions regarding the use of SQL Server, please contact Microsoft Corporation technical support.

SQL Server Properties

No special configuration is required. This application works when SQL Server is installed with default options recommended during installation process. However, someone else may have installed your server earlier and you don't know what options were modified. For this reason, we provide these screenshots that display SQL Server configuration known to work, but don't rush to reconfigure your server.

Database Initialization

We provide two ways to create your database and all internal objects. One way is to attach the database file supplied with the software. The second way is to build your database by executing provided SQL scripts.

1) By attaching database file

2) By executing SQL scripts

Step 1 - Attach database file

Start "Enterprise Manager" tool

Start -> Programs -> Microsoft SQL Server -> Enterprise Manager

Locate your server.

Locate "Databases" folder. Right-click on "Databases", select "All Tasks", select "Attach Database" menu item.

"Attach Database" window is displayed.

Locate the BugTracker.mdf file copied during Software Installation step.

Specify a name for this database in the field "Attach as". Use a unique and descriptive name such as "BugTracker". This is how this SQL server, other SQL servers, and database administrator(s) will know your database. You will not be able to simply rename it after it is attached.

Specify "sa" (system administrator) as the owner of this database.

Steps 2, 3, and 4 - Not applicable

The attached database already contains all objects.

Step 5.1 - Create IUSR user and grant permissions

Start "Query Analyzer" tool

Start -> Programs -> Microsoft SQL Server -> Query Analyzer

Connect to your SQL server as an Administrator or "sa" user.

Use menu File -> Open to open SQL scripts.

Open script "5.1 Manage Users&Access.sql"
Make sure first line displays correct database name.
IF YOUR WEB SERVER AND SQL SERVER ARE SEPARATED
	First, determine how IIS setup created the IUSR account. It may look like a) HOST\IUSR_HOST or b) DOMAIN\IUSR_HOST The easiest way to find out this is to open Properties -> Security of any file or folder on your local disk, click on "Add" button, find the IUSR account and double-click on it, but DO NOT click "Ok" button. The complete User ID is displayed in the box. Remember or write it down, then cancel this action. Hard-code the name of your web server (host) in line 17. This line should look like: SET @WEBSERVER = 'HOST' If IUSR preceded with domain information (option "b" above) then hard-code this domain name in line 18. This line should look like: SET @DOMAIN = 'DOMAIN' The HOST and DOMAIN should be substituted with the actual names.

Execute the script.

If you were unable to execute this script read this chapter.

Step 5.2 - Set Database Options

Open script "5.2 Set DB Options.sql"
Make sure first line displays correct database name.
Execute the script.

Step 6 - Not applicable

The attached database already contains all table data.

Step 1 - Build database

Start "Query Analyzer" tool

Start -> Programs -> Microsoft SQL Server -> Query Analyzer

Connect to your SQL server as an Administrator or "sa" user.

Use menu File -> Open to open SQL scripts.

Open script "1.1 Create BugTracker Database.sql".
If you prefer a name of your database other than "BugTracker" specify this name in line 9. In this case you must specify exactly the same name in all other SQL scripts used herein.
Execute the script.

Step 2, 3, and 4 - Create All Database Objects

Open script "2.2 Create All Tables and Indexes.sql".
Make sure first line displays correct database name.
Execute the script.

Repeat this process for
"3.2 Create All Views.sql" and
"4.2 Create All StoredProcedures.sql" scripts.

Step 5.1 - Create IUSR user and grant permissions

Open script "5.1 Manage Users&Access.sql"
Make sure first line displays correct database name.
IF YOUR WEB SERVER AND SQL SERVER ARE SEPARATED
	First, determine how IIS setup created the IUSR account. It may look like a) HOST\IUSR_HOST or b) DOMAIN\IUSR_HOST The easiest way to find out this is to open Properties -> Security of any file or folder on your local disk, click on "Add" button, find the IUSR account and double-click on it, but DO NOT click "Ok" button. The complete User ID is displayed in the box. Remember or write it down, then cancel this action. Hard-code the name of your web server (host) in line 17. This line should look like: SET @WEBSERVER = 'HOST' If IUSR preceded with domain information (option b) above) then hard-code this domain name in line 18. This line should look like: SET @DOMAIN = 'DOMAIN' The HOST and DOMAIN should be substituted with the actual names.

Execute the script.

If you were unable to execute this script read this chapter.

Step 5.2 - Set Database Options

Open script "5.2 Set DB Options.sql"
Make sure first line displays correct database name.
Execute the script.
Note: Use database Properties -> Options tab to manually adjust database options according to your specific requirements.

Step 6 - Load Table Data

Data files are the text files supplied with the software and located in Setup folder on the installation disk. The data file names start with "DataFor_" words.

If you are executing this procedure remotely, you must either copy these files to your server's local directory or share this folder and map to it from your server. In either case, the server must be able to access the location specified in the script. When this step is completed remove any "DataFor_" files copied earlier or stop sharing the folder.

Open script "6.1 Load Data.sql"
Modify line 6 and specify the path to the data files.
Make sure first line displays correct database name.
Execute the script.

You may have a situation when a "fixed" SQL Server user account is preferred or in a combination with IUSR. In this case, create a new SQL Server Login using "SQL Server Authentication", grant access to all necessary databases, grant object permissions such as SELECT, INSERT, UPDATE, and modify DBC.asp file as described in "Connecting Bug Tracking Software and Database" chapter.

Database Properties

To open database properties use the "Enterprise Manager" tool. Locate your new database. Right-click on it and select "Properties". If "Enterprise Manager" is already open, press F5 to refresh the screen.

No special configuration is required. Recommended settings are shown here. Refer to SQL Server documentation regarding the purpose of each option.

Note that database option "Auto Close" is selected. This allows the database to commit all buffers and close files when no one is using it. This gives you a better protection against database corruption due to a power failure for example. However, if your server plugged to a UPS backup system you can turn "Auto close" off for better performance.

Database Maintenance Plan

Once your bug tracking system is installed and operational, we recommend you to create a "Database Maintenance Plan".
This feature of Microsoft SQL Server performs two major tasks. First, it backs-up your database(s), and second, it optimizes and defragments tables and indexes resulting in improved database performance.

Click here for details.

ODBC

No special configuration is required when IIS and SQL Server located on the same computer. All necessary drivers are installed during SQL Server setup.

When IIS is separate from you SQL server it may not have the SQL Server drivers.

To find out whether SQL driver is installed, go to
Control Panel -> Administrative Tools -> Data Sources / ODBC

Go to "Drivers" tab. See if you have "SQL Server" among other items.

The easiest way to add these drivers is to install SQL Server management components on your web server. SQL Server setup program allows you to install only administration tools without database server components. Alternative option is to download latest MDAC package from Microsoft.

Connecting Bug Tracking Software and Database

No additional configuration is required when IIS and SQL Server are located on the same computer and the name of your bug database is "BugTracker".

The software component communicates with the database component via standard ODBC interface. The file DBC.asp defines connection parameters. After software is installed and your bug database is initialized you need to specify how software component should connect to your database.

1) Locate DBC.asp file, remove read-only permissions, and open it for editing. The DBC.asp is located in folder "wwwroot\<instance>\lib" where <instance> is the directory created by you during Software Installation step (such as "BugTracker").

2) Go to line 9.

Const CONN_STR = "DRIVER=SQL Server; SERVER=127.0.0.1; DATABASE=BugTracker; Network=DBMSSOCN; Address=127.0.0.1,1433; OemToAnsi=Yes; TranslationDLL=Yes"

Parameters are separated with ";" character. Modify parameter as provided:

SERVER=	When IIS and SQL Server on the same computer leave 127.0.0.1, otherwise the IP address or DNS name of your SQL Server computer. IP address works faster, but requires it to be static.
DATABASE=	The name of your bug database specified during Database Initialization step.
Address=	The same IP address or DNS name as the SERVER parameter, plus SQL Server port number. IP address and port are separated with a "," character. Default port is 1433.
- all other -	- no changes -
The connection string shown above assumes IUSR_<host> windows account as the user of the database. The benefit of this setup is that user authentication is done internally in a secure manner and you don't have to hard-code UserID and password in this file. If you have to use "fixed" user account, create a new SQL Server user using "SQL Server Authentication" authentication type, manually grant access to the bug database and database objects, and add the following two parameters:
USER ID=	<username> Note: You should NOT use the "sa" or any other administrative SQL Server account for security reasons.
PASSWORD=	<password>

3) Save the file and test whether you are able to login into bug tracking system.

When all works, apply read-only permission to DBC.asp.

SMTP Mail Service

The email notification mechanism plays an important role in the bug tracking process and it is highly recommended to get it working as soon as possible.

Before you begin

You should complete all the steps from above and have access to the Administrator' interface
From "Administration Task" page select "Email Configuration"
In "Email Configuration"

Field "Mailroot". To let the system locate your Mailroot folder leave it blank, otherwise specify the path.
Modify field "From.AccountName:" from its default value (BUGTRACKER <bugtracker@127.0.0.1>) and replace 127.0.0.1 with the fully-qualified domain name of this server (i.e. host.domain.com).
Note, it is permitted to specify an IP address here, however, all delivery notifications and bounced back mail for the messages sent outside of your LAN are likely to be lost.
The word "BUGTRACKER" is an alias to the address after it. It is not used for email routing, but most email clients recognize and display it in the "From" field instead of the actual email address. You can change it to anything else, but be careful with spaces and other special characters.
Modify filed "Administrator:" from its default value (postmaster@127.0.0.1) and specify your valid and known to work email address.
Field "MailEnabled" should be "Yes".

Use the "Test" button to send test email to the "Administrator".

This documentation assumes that the server you are configuring is NOT you primary mail server. The configuration described later in this chapter tells SMTP to forward all the mail elsewhere. If this server IS your primary mail server or you are running other email software on this computer configuration is somewhat more complicated.

The SMTP Service is designed to receive email messages from the network, however it can also process RFC-822 formatted text files placed directly into its queue. Although, this feature is not documented it appears to be very reliable way to send mail from a web application. Besides, since BugTracker's mail routine produces standard RFC-822 formatted text file, other mail sending utilities such as "sendmail" can be used.
We can also provide alternative routine which uses Microsoft CDO.Mail object.

How SMTP works

When SMTP receives a message it process it in one of the following ways:

Deliver to local users
Reject
Forward to another host

The SMTP documentation referes to this action as "Deliver to local users". This could be very confusing. What local users? Who are these users? I have only "Administrator's" login on this computer. The answer is quite simple; SMTP doesn't care about actual user accounts. The following diagram outlines the actions taken by the SMTP server when it processes a message.

SMTP takes domain portion of the TO: address (user@domain.com) and matches it against all the "Domains" (Domain Name) defined in its configuration. Domains can be defined as host.domain, domain, or as a pattern .com, .net.
Match not found
	Move message to "Badmail" folder and send non-delivery report (NDR) back. When SMTP generates NDR, the original message "From" address becomes "To" address and is handled the same way as any other message. If there is a problem with "From" address, the NDR also ends-up in "Badmail" directory.
Match is found
	SMTP looks into the "Type" field for this domain.
		Type is "Local" (either "Default" or "Alias")
			Process message locally. Local processing depends on LDAP configuration (see SMTP Properties -> LDAP Routing tab).
			LDAP is enabled.
				SMTP server takes the user portion of the TO: address (user@domain.com) and searches the data source specified in the LDAP settings.
				Match is found
					Move message to "Drop" folder.
				No match found
					Move message to "Badmail" folder and sends non-delivery report (NDR) back.
			LDAP is disabled.
				SMTP assumes that user is valid and moves the message to "Drop" directory.
		Type is "Remote"
			One or more attempts are made to forward the message to that remote domain.
			Success
				Message is sent
			Failed
				Move message to "Badmail" folder and send non-delivery report (NDR) back.

This bug tracking system uses IIS SMTP Service to send email notification messages to its users. The system does not process any messages received by SMTP such as user replies to the Administrator and "Undelivered" reports. For this reason we use "Reply-To:" field, which specifies appropriate address where reply should be sent to and the rest of the process depends on you mail system and actions of actual users.

Configuration is done through "Internet Services Manager" interface.
The goal of this configuration is to instruct SMTP service to forward all messages not specifically designated for this host to a remote mail server.

Here are two exaples:

Assume your server is called server1 and you domain is called mydomain.com.

admin@mydomain.com - This address IS NOT specifically designated for this host.
admin@server1.mydomain.com - This address IS specifically designated for this host.

The default configuration only instructs SMTP to process mail designated for this host and reject all other mail. In the list of the Domains there will be only one item - your server. If server is a member of a domain, it is displayed as host.domain; otherwise only host name is displayed.
In order to forward all mail, which is not designated for this host to a remote mail server we need to define these domains as "Remote". Right-Click on "Domains" and go to New -> Domain...
Specify that this is going to be a remote domain.
You may ask, which domains I have to define? All the domains that you want this server to forward. This includes domains of your external users. You can define each domain individually, however it would be more beneficial to specify a pattern such as *.com .
Repeat this process for .net, .org, [ .cc, .tv ]. The result should be as shown on this picture.

Now, for each record just added, open its "Properties" and specify options as shown. The "smart host" is your primary mail server. It can be specified as a fully-qualified domain name (FQDN) or as an IP address enclosed in [] brackets.

No configuration is necessary in "Advanced" properties.

The following images display SMTP configuration known to work. If necessary, you may adjust these parameters according to your requirements. Please refer to SMTP help regarding the purpose and acceptable values of each parameter. Options that are not shown here are either not important or set to default values. LDAP Routing is disabled.

This concludes initial software installation and system configuration. Now, you may proceed to Administrator interface and start tailoring the application to your needs. Also, we recommend you to read Security chapter.