Personal Bug Tracking with Mantis on Windows

Whenever I do work for a client, I check my changes into their version control system, and I update my tasks using their bug tracking system (when they have one). Independently of that, I also use my own personal version control system to track the changes I make as I develop. But, I've never used a personal bug tracking system. It didn't take much to convince me that I should change my evil ways, and so I did.

After hearing about the hassles a client had with the closed source product TestTrack Pro from Seapine Software (the outgoing mail port is hard coded) I decided to go with an open source product. If I need to tweak things, I don't want to depend on the owners of the source to get around to making the changes I want, if they make them at all. Free is nice, but not crucial. GBB Services spends thousands of dollars every year on development software (and thousands more on hardware). We're willing to spend money for the right products!

The best known open source bug tracker seems to be Bugzilla, and I downloaded it. That's about as far as I got. It's way too complicated for my purposes, and I dumped it quickly. Then I heard about Mantis. "Easy to install, easy to customize, free, open source, works on Windows 2000." It sounded good.

It took me a while to get Mantis working, mostly because I didn't know what I was doing. Knowing what I know now, I can get Mantis installed on a fresh machine a LOT faster. With this note I'll be sharing some of what I learned.

Prerequisites

Mantis requires that at least two other open source programs are installed and working. They are the database application MySQL, and the scripting language PHP. I didn't have either before I started, so I had to install and use both for the first time, and then I had to coordinate their use with Mantis. It's no problem, if things go well. I'll be mentioning some diagnostics you can run to immediately tell if things are going well or not.

Also, Mantis requires that a web server be installed. I've gotten it working on two machines: a windows 2000 machine with IIS running, and a windows XP machine with Apache running. Some details are different, depending on the http server used. If you don't care which one you use, it's probably less of a hassle to work with IIS.

Incidentally, every bug tracking product I know of requires a database program, and just about all the bug tracking systems are accessed via a browser, which means that a web server has to installed. You won't get away from these requirements by avoiding Mantis!

If you haven't installed IIS, Apache, or some other http server, you'll need to that first. I've provided some pointers, but it's not the main emphasis of this essay. Also, if you care about security, you won't find any help here. I'm not really concerned about password security (for web server administration, mysql administration, or Mantis administration) since I'm the only one who's accessing my machines. Finally, if you're interested in setting up email notifications, you won't find any help here. I don't need them for personal bug tracking.

Other Sources of information

Setting up Mantis

Free Download

In this essay I'll be recommending that you create various diagnostic files which are to be placed in the location http://localhost/mantisinfo/. Since I've already created them and placed them in the zip file mantisinfo.zip (1,238 bytes), you can save yourself some typing (or at least some cut and paste mouse clicking) by downloading that zip file. Just create the subdirectory mantisinfo under the web root and unzip the files there.

Installing a web server

This section is extremely sketchy compared to the other sections. It's the bare minimum you'll need to get through the installation.

If you're looking to install IIS on a Windows 2000 machine, open up the control panel, click on "Add/Remove Programs", then click on "Add/Remove Windows Components" (which is a button to the left of the "Currently installed programs" list). If "Internet Information Services (IIS)" is unchecked, check it. Hit "Next" and get your Windows 2000 Professional installation disk. Once you've successfully installed IIS, you'll probably want to become familiar with the command line incantations "net start w3svc" and "net stop w3svc".

If you're looking to install the Apache http server, download the installation program and follow the instructions. The configuration file you'll have to become familiar with is "C:\Program Files\Apache Group\Apache\conf\httpd.conf". Being able to type "net start apache" and "net stop apache" at the command line will also come in handy.

Confirming that the web server works

Create a page "index.html" in your (web site) root directory, and then point your web browser to it. You will probably want to use the url http://localhost/index.html

Installing MySQL

To install MySQL, unzip "mysql-4.0.17-win.zip", placing the files in some temporary directory. Then run the "setup.exe" program. It will offer to install MySQL in the "C:\mysql" directory. That's fine with me. I then choose the "Typical" option and let the installation program run to completion.

The next step is to copy one of the files my-huge.cnf, my-large.cnf, my-medium.cnf, my-small.cnf in "C:\mysql\" to "C:\my.cnf". This becomes the initialization file for MySQL. The "huge", "large", etc descriptors refer to the amount of memory and disk space of the local machine. I've gone with copying "my-medium.cnf" to "C:\my.cnf".

# Remove the next comment character if you are not familiar with SQL
#safe-updates

# Remove the next comment character if you are not familiar with SQL
safe-updates

Confirming that MySQL works

At this stage we're ready to test the installation. The first thing you have to do is get the server component of MySQL working. I like to get it working as a windows service, and the way to do that is to open a command line window and type "c:\mysql\bin\mysqld.exe --install", and hit return. Your interaction should go something like:

C:\temp>c:\mysql\mysqld.exe --install
Service successfully installed.
C:\temp>

To check that this went well, bring up the services window, and look at the properties of the mysql service. You should see that the "path to executable" is c:\mysql\bin\mysqld.exe MySQL . If it isn't, change it! Firstly, uninstall the service via "mysqld --remove", ie

C:\temp>c:\mysql\mysqld.exe --remove
Service successfully removed.
C:\temp>

and then play it safe by going into the mysql\bin directory and installing the service via a fully qualified executable: ie

C:\temp>cd \mysql\bin

C:\mysql\bin>c:\mysql\bin\mysqld.exe --install
Service successfully installed.

C:\mysql\bin>

Assuming that went well, the next step is to start the service. Again, from the command line:

C:\temp>net start mysql
The MySQL service is starting.
The MySQL service was started successfully.

C:\temp>

C:\temp>net start mysql
System error 2 has occurred.

The system cannot find the file specified.
C:\temp>

you need to fix this before continuing. The first thing I would check is the "path to executable" as described above.

OK, now let's test the that the server is working by running some client programs. The easiest thing to try is to type "c:\mysql\mysql.exe" (not "mysqld" this time, we want the client program, not the server daemon). You should get a welcome message and the mysql prompt "mysql>". Type "exit" to quit the application. The entire interaction should look something like:

C:\temp>c:\mysql\bin\mysql
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 1 to server version: 4.0.17-max-debug

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> exit
Bye

C:\temp>

I'm paranoid, so I like to run sanity tests. For example, if you switch the mysql service off, the interaction at the command line should fail. Here's the results of an interactive session:

C:\temp>net stop mysql
The MySQL service is stopping.
The MySQL service was stopped successfully.

C:\temp>c:\mysql\bin\mysql
ERROR 2003: Can't connect to MySQL server on 'localhost' (10061)

C:\temp>net start mysql
The MySQL service is starting.

The MySQL service was started successfully.

C:\temp>c:\mysql\bin\mysql
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 1 to server version: 4.0.17-max-debug

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> exit
Bye

C:\temp>

At this stage the MySQL stage of the installation is done. If you haven't got the server running, there isn't much point to doing anything else. You've got to find out why it's not working. Good luck!! If you can't, you can try running mysql as a standalone application ("mysqld --standalone").

Installing php

The php site is at http://www.php.net/ . The details of what to get are different, depending on whether you're using IIS or Apache as your web server. Either way, you'll want to get the installer. See below ...

Installing php in an IIS environment

Get the file "php-4.3.4-installer.exe" (1,068,496 bytes) from the php download section at http://www.php.net/downloads.php. Look for "PHP 4.3.4 installer [1,043Kb] - 03 November 2003".

Run the program "php-4.3.4-installer.exe". I just go with the defaults. For my Windows2000/IIS system, the Server Type was identified as "Microsoft IIS 4 or higher", which is correct. Run the installation to the end. Skip the next section and got to Confirming that php works.

Installing php in an Apache environment

Get the file "php-4.3.4-installer.exe" (1,068,496 bytes) from the php download section at http://www.php.net/downloads.php. Look for "PHP 4.3.4 installer [1,043Kb] - 03 November 2003".

Run the program "php-4.3.4-installer.exe". I just go with the defaults, EXCEPT for picking the Server Type as "Apache". For my WindowsXP/Apache system, the Server Type was identified as "Microsoft IIS 4 or higher", which is NOT correct. Run the installation to the end.

Now get "php-4.3.4-Win32.zip" (6,978,847 bytes) from the php download section at http://www.php.net/downloads.php. Look for "PHP 4.3.4 zip package [6,815Kb] - 03 November 2003".

Unzip the contents of "php-4.3.4-Win32.zip" in some temporary directory. Now move the unzipped "sapi" subdirectory so that it becomes a subdirectory of "c:\php". Now move the file c:\php\php4ts.dll to c:\php\sapi\php4ts.dll.

The final step is to modify the Apache configuration file "httpd.conf". Firstly, stop the apache server via the command line: "net stop apache". Add the following 3 lines to httpd.conf

Note the backslashes, "\", in "C:\php\sapi\php4apache.dll". The notes in c:\php\install.txt will tell you that you can use forward slashes. Not true on my machine!

C:\temp>net start apache
The apache service is starting.
The apache service could not be started.
A system error has occurred.
System error 1067 has occurred.
The process terminated unexpectedly.
C:\temp>

C:\temp>net start apache
The apache service is starting.
The apache service was started successfully.
C:\temp>

Confirming that php works

Now it's time to test that the php installation is working. Following the advice in Amandeep Jawa's installation notes, I created the file helloPHP.php. It contains the following text:

For fun, you might also want to create a file infoPHP.php that contains only one line:

Confirming that mysql and php work together

Finally, now that you know that MySQL works fine, and php works fine, it's time to test that they work fine together.

To do that, I stole shamelessly from Amandeep Jawa's notes, and created the file helloSQL.php which contains the following:

<html>
<head><title>PHP and SQL Integration Test</title></head>

<body>

<?php
$link = mysql_connect("localhost", "", "") or die("Could not connect");
print "Connected successfully";

$query = "SELECT now()";
$result = mysql_query($query)
or die("Query failed");

print "<table>\n";
while ($line = mysql_fetch_array($result, MYSQL_ASSOC)) {
print "\t<tr>\n";
foreach ($line as $col_value) {
print "\t\t<td>$col_value</td>\n";
}
print "\t</tr>\n";
}
print "</table>\n";

mysql_close($link);
?>

</body>

</html>

Warning: mysql_connect(): Can't connect to MySQL server
on 'localhost' (10061) in C:\inetpub\wwwroot\mantisinfo\helloSQL.php on line 6
Could not connect

On the other hand, when the MySQL server is turned on (eg. via "net start mysql"), I get the following two lines:

Assuming that you're getting something like the above two lines, it's finally time to install Mantis itself.

Installing Mantis

Go to the Mantis site at http://mantisbt.sourceforge.net/ and download the 0.18.0 release. You'll want to get the file "mantis-0.18.0.tar.gz" (543,328 bytes).

The first thing to do is to unzip "mantis-0.18.0.tar.gz", keeping the directory structure intact. All the files will be rooted at "mantis-0.18.0". The next step is to move that Mantis root directory to "c:\inetpub\wwwroot\mantis" (assuming that the root directory of your http server is "c:\inetpub\wwwroot"). The last thing to do to make sure that you have a minimal installation working is to copy the file config_inc.php.sample to config_inc.php

First Mantis tests

You should get a diagnostics page that shows 5 colored boxes, with all of them green, except for the second one. You should have green ( GOOD ) for "Opening connection to database on host" but red ( BAD ) for "Selecting database"

Continuing the Mantis installation

To make life a little easier, I'll stick with defaults and call the database "bugtracker". To do this, open a command line window and type
"c:\mysql\bin\mysql", and hit return. Assuming that the mysql server is running, you should get the mysql prompt "mysql>". At that prompt type
"CREATE DATABASE bugtracker;" and hit return. These are sql instructions, and the semicolon is necessary. By the way, if you're unfamiliar with sql, I don't think it will matter for working with Mantis. Once you've set things up, you really don't need to do much with MySQL at all. If all went well, you should see something like the message:
Query OK, 1 row affected (0.02 sec)
The mysql prompt should be available again. Type "exit" and hit return. You're should now be back to seeing the command line prompt. Now type
"c:\mysql\bin\mysql bugtracker < c:\inetpub\wwwroot\mantis\sql\db_generate.sql".
(or type "cd c:\inetpub\wwwroot\mantis\sql", hit return, and type
"c:\mysql\bin\mysql bugtracker < db_generate.sql".

C:\temp>c:\mysql\bin\mysql
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 6 to server version: 4.0.17-max-debug

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> CREATE DATABASE bugtracker;
Query OK, 1 row affected (0.01 sec)

mysql> exit
Bye

C:\temp>cd c:\mysql\bin
C:\mysql\bin>mysql bugtracker < c:\inetpub\wwwroot\mantis\sql\db_generate.sql

C:\mysql\bin>

More Mantis tests

If, like me, you don't want email notification, and you don't want to see email error information for the email capability you're not using, there's one more step.

You should now be able to point to http://localhost/mantis/index.php and get a login form. Using the Username "administrator" and the Password "root", you should be able to get in.

Life with Mantis

You should be aware of the following configuration files:
c:\my.cnf (the configuration file for MySQL)
c:\winnt\php.ini (the configuration file for php)
c:\inetpub\wwwroot\mantis\config_inc.php (the configuration file for Mantis).

Something you might want to do is to have two or more completely separate Mantis projects. One possible reason might be to create a throwaway project that you can use to experiment with. Another reason might be to keep client projects completely separate from each other.

One way to do have another Mantis project is by copying the "mantis" subdirectory to a new "mantisA" subdirectory.

Then go to c:\inetpub\wwwroot\mantis and edit config_inc.php The default database used by Mantis is "bugtracker". Since the whole point of a second Mantis installation is to keep the Mantis databases separated, change the default "bugtracker" in config_inc.php to something else, say "bugtrackerA"

C:\temp>c:\mysql\bin\mysql
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 6 to server version: 4.0.17-max-debug

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> CREATE DATABASE bugtrackerA;
Query OK, 1 row affected (0.01 sec)

mysql> exit
Bye

C:\temp>

c:\inetpub\wwwroot\mantisA\sql

c:\mysql\bin\mysql bugtrackerA < db_generate.sql

Incidentally, if just after creating the database bugtrackerA you decide to change your mind, you can destroy the database by using the mysql client and typing

DROP DATABASE bugtrackerA;

Backing Up

Backing up and restoring the database is fairly simple. You might want to try this out with a throwaway project first. I like to use my Windows 2000/IIS Mantis setup for experiments, and my Windows XP/Apache Mantis setup for the real thing.

To backup a project associated with the "bugtracker" database, you need to dump the database into a text file, say "bugtrackerBackup.txt".

C:\>cd temp

C:\temp>cd c:\mysql\bin

C:\mysql\bin>mysqldump bugtracker > bugtrackerBackup.txt

C:\mysql\bin>

Restoring the database from the text file is done via redirecting bugtrackerBackup.txt as input. If all goes smoothly, the command line session looks like:

C:\>cd temp

C:\temp>cd c:\mysql\bin

C:\mysql\bin>mysql bugtracker < bugtrackerBackup.txt

C:\mysql\bin>

If things don't go this smoothly, you probably need to delete and recreate the database before doing the redirection. Here's an example:

C:\temp>cd c:\mysql\bin

C:\mysql\bin>mysqldump bugtracker > bugtrackerBackup.txt

C:\mysql\bin>mysql bugtracker < bugtrackerBackup.txt
ERROR 1050 at line 11: Table 'mantis_bug_file_table' already exists

C:\mysql\bin>mysql
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 3 to server version: 4.0.17-max-debug

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> DROP DATABASE bugtracker;
Query OK, 0 rows affected (0.13 sec)

mysql> CREATE DATABASE bugtracker;
Query OK, 1 row affected (0.00 sec)

mysql> exit
Bye

C:\mysql\bin>mysql bugtracker < bugtrackerBackup.txt

C:\mysql\bin>