Mantis Installation

Installing the Mantis Bug Tracking System

Amandeep Jawa (deep AT worker DASH bee DOT com)
Worker Bee Software
Document Version 0.9

Introduction:
This document describes how to install the Mantis bug tracking system. It was created while installing Mantis on Red Hat Linux 7.2 but should be easily modified for other Linuxes & nonetheless provide good information for Windows. It is in no way intended to supercede offical documentation from the Mantis web site http://mantisbt.sourceforge.net.

Contents:
This document is divided into the following sections.

Installing PHP & MySQL
Verifying HTTPD, PHP & MySQL
Installing Mantis
Securing Mantis

Software Requirements:

MySQL database
PHP 3.0.13 or newer
Apache or some other web server

Note that this file was actually tested with the following installed RPMs on a Red Hat 7.2 Linux installation:

mantis-0.17.0.tar.gz
MySQL-3.23.47-1.i386.rpm
MySQL-client-3.23.47-1.i386.rpm
MySQL-devel-3.23.47-1.i386.rpm
MySQL-shared-3.23.47-1.i386.rpm
php-4.0.6-7.i386.rpm
php-mysql-4.0.6-7.i386.rpm

Document Conventions:
This document was created with the following conventions:

Text in green like this: cd /root/downloads, are commands that should be typed on the commandline & then entered by hitting the enter key
Text in black like this refers to a literal value - i.e. things that should appear on your version just as they are written in this document such as: Red Hat Linux 7.1 Operating System (Binary CD 1 of 2)
Items in red denote critical instructions or information.
Items in orange denote areas of this document that need to be fixed or completed.
Items in dark green italics represent areas of this text that are placeholders for values from the user's system. The reader should replace these areas with the appropriate value from their specific installation.

Installing PHP & MySQL

Before you install Mantis you should ensure that you have a fully functioning web server (HTTPD) installation with PHP/MySQL support. If you have already installed MySQL and PHP skip this section & start with the verify section below. If you are doing a fresh install, start here.

Login to your server machine as root user.
(Optional) Create a downloads directory to store your rpms in: mkdir /root/downloads
(Optional) Create a mysql directory to store your MySQL rpms in: mkdir /root/downloads/mysql
Now download the following MySQL rpms from your favorite RPM site (or www.mysql.com). Note that the versions listed below represent the one I found on the web, newer ones may exist. Store the files in the downloads/mysql directory you created (if you made one).

MySQL-3.23.47-1.i386.rpm
MySQL-client-3.23.47-1.i386.rpm
MySQL-devel-3.23.47-1.i386.rpm
MySQL-shared-3.23.47-1.i386.rpm

Now install each of the MySQL rpms:

Cd to the downloads directory: cd /root/downloads/mysql
Install all the rpms just downloaded:rpm -i *.rpm
If the install succeeds, the command prompt will return with no errors & then you will get a message that looks something like this:

Preparing db table
Preparing host table
Preparing user table
Preparing func table
Preparing tables_priv table
Preparing columns_priv table
Installing all prepared tables
020219  1:10:40  /usr/sbin/mysqld: Shutdown Complete


PLEASE REMEMBER TO SET A PASSWORD FOR THE MySQL root USER !
This is done with:
/usr/bin/mysqladmin -u root -p password 'new-password'
/usr/bin/mysqladmin -u root -h localhost.localdomain -p password 'new-password'
See the manual for more instructions.

Please report any problems with the /usr/bin/mysqlbug script!

The latest information about MySQL is available on the web at
http://www.mysql.com
Support MySQL by buying support/licenses at https://order.mysql.com

Starting mysqld daemon with databases from /var/lib/mysql

To confirm the installation type: rpm -qa | grep MySQL & you should get results that look like:
```
MySQL-shared-3.23.47-1
MySQL-3.23.47-1
MySQL-devel-3.23.47-1
MySQL-client-3.23.47-1
```

As recommended, run the two lines given in the message to set your root password. Make sure you remember the root password:

Type /usr/bin/mysqladmin -u root -p password '<YOUR NEW PASSWORD>'
When you are prompted with Enter password: hit the <RETURN> key
Type /usr/bin/mysqladmin -u root -h localhost.localdomain -p password '<YOUR NEW PASSWORD>'
When you are prompted with Enter password: hit the <RETURN> key
To confirm you did this correctly, type: mysql -uroot
You should get an error that looks like this: ERROR 1045: Access denied for user: 'root@localhost' (Using password: NO)
Now try mysql -uroot -p <YOUR NEW PASSWORD>

You should get something that looks like this:

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 6 to server version: 3.23.47

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

Now exit mysql by typing: exit
You have successfully installed MySQL.

(Optional) Create a php directory to store your php rpms in: mkdir /root/downloads/php
Now download the following php rpms from your favorite RPM site. Note that the versions listed below represent the one I found on the web, newer ones may exist. Store the files in the downloads/php directory you created (if you made one).

php-4.0.6-7.i386.rpm
php-mysql-4.0.6-7.i386.rpm

Now install each of the php rpms:

Cd to the downloads directory: cd /root/downloads/php
install all the rpms just downloaded:rpm -i *.rpm
If the install succeeds, the command prompt will return with no errors. Note, if you get a message that looks something like this:package php-4.0.6-7 is already installed - that is fine but you will still need to install the other php rpm - so type: rpm -i php-mysql*.rpm
To confirm the installation type: rpm -qa | grep php & you should get results that look like (maybe more than this):
```
php-mysql-4.0.6-7
php-4.0.6-7
```

You have now installed php & MySQL

Back to contents

Verifying HTTPD, PHP & MySQL

Before you install Mantis you should ensure that you have a fully functioning web server (HTTPD) installation with PHP/MySQL support. If you are absolutely sure that your HTTPD/PHP/MySQL configuration is working you can skip this section, but this section is very simple & is therefore recommended. All of our tests were done with Apache as our HTTPD server but other HTTPD servers should work the same.

Verify that your web server installation is working correctly check one of its pages such as http://<YOUR SERVER'S IP ADDRESS>. At the very least you should get some default page - like the Apache test page.
Now verify that your HTTPD/PHP connection is working:
- Create a file named hello.php in your web server's root directory.
- Enter the following text into the file:
```
<html>
	<head>
		<title>PHP Test</title>
	</head>
	<body>
		<?php echo "Hello World<p>"; ?>
	</body>
</html>
	  
```
- You should now confirm that you can access it from your web browser at some URL such as http://<YOUR SERVER'S IP ADDRESS>hello.php
- You should see a page that simply says Hello World
Now verify that your Apache/PHP/MySQL connection is working:
- Create a file named helloSQL.php in your web server's root directory.
- Enter the following text into the file:
```
<?php
// Connecting, selecting database
$link = mysql_connect("<YOUR DATABASE HOSTNAME OR IP>", "<YOUR DATABASE USER NAME>", "<YOUR DATABASE PASSWORD>")
    or die("Could not connect");
print "Connected successfully";


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


// Printing results in HTML
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";


// Closing connection
mysql_close($link);
?>
```
- Change the values of <YOUR DATABASE HOSTNAME OR IP>, <YOUR DATABASE USER NAME>, & <YOUR DATABASE PASSWORD> to match your system & database installation. Note if you have just now installed MySQL via the instructions above, use: localhost for the hostname, root for the user name & whatever you set the new password to for the password. If you do use the root username delete this file (helloSQl.php) after you finish these tests. Leaving a root password lying around is a BAD idea.
- You should now confirm that you can access it from your web browser at some URL such as http://<YOUR SERVER'S IP ADDRESS>helloSQL.php
- You should see a page that simply says Connected Successfully & then contains the date on the next line.
- At this point you have confirmed that HTTPD, MySQL & php are installed and working properly.

Back to contents

Installing Mantis

Now that you have an HTTPD server, MySQL & php installed, you can now install Mantis.

Login to your server machine as root user.
(Optional) Create a downloads directory to store Mantis in: mkdir /root/downloads
(Optional) Create a mantis directory to store your Mantis downloads in: mkdir /root/downloads/mantis
Download the Mantis installer from http://mantisbt.sourceforge.net/download.php3, as of this writing, the current version is 0.17.0. Store the files in the downloads/mantis directory you created (if you made one).
Unpack the Mantis tarball:

Cd to thedownloads/mantis directory: cd /root/downloads/mantis
Unpack it with this command: tar zxvf *.gz

Copy the unpacked directory to whatever directory you are using as your web root directory: mv mantis-0.17.0 <YOUR WEB ROOT>, for example on my system that is mv mantis-0.17.0 /var/www/html
For simplicity, rename the directory you just moved to mantis: mv <YOUR WEB ROOT> mantis-0.17.0 <YOUR WEB ROOT> mantis
If you are using the default MD5 password encryption you can skip the next few steps & continue following instructions here. If you wish to change the password encryption configuration continue.

Edit the db_generate.sql file in the <YOUR WEB ROOT>/mantis/sql directory with your favorite text editor.

Go to the very end of the file & find the section that looks like this:

# replace the 4th argument after VALUES with your chosen method of encryption
# default is MD5
#   PLAIN = root
#   CRYPT = MNYm8SfoJlvIY
#   MD5   = 63a9f0ea7bb98050796b649e85481845
INSERT INTO mantis_user_table
        (id, username, email, password, date_created, last_visit, enabled, prote
cted, access_level, login_count, cookie_string)
VALUES
        ( '0000001', 'administrator', 'admin', '63a9f0ea7bb98050796b649e85481845',
 NOW(), NOW(), '1', '1', '90', '0', 'MN91uSF/JIhos8bcda8acc2ead8d60749ad019e56
b54fadkPGTyoBgNBQf91563adc2f7337f566cc3d2c792bc3c-10728595');

If you would like to use CRYPT as the encryption method, change the part that reads
```
'admin', '63a9f0ea7bb98050796b649e85481845'
```
to
```
'admin', 'MNYm8SfoJlvIY'
```
If you would like to use PLAIN as the encryption method, change the part that reads
```
'admin', '63a9f0ea7bb98050796b649e85481845'
```
to
```
'admin', 'root'
```

Now create a Mantis database using the mysql commandline interface:

Launch the commandline interface: mysql -uroot -p<YOUR PASSWORD>

You will see something like:

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 12 to server version: 3.23.47

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

Now create the database by typing: CREATE DATABASE <YOUR DATABASE NAME>; with whatever database name you choose. For example, on my system I used: CREATE DATABASE mantis_db;
You will see something like: Query OK, 1 row affected (0.00 sec)
Quit the commandline interface: exit

Now create the Mantis database tables:

Cd to the Mantis directory's sql directory: cd <YOUR WEB ROOT>/mantis/sql
Run mysql with the generate script: mysql -uroot -p<YOUR PASSWORD> <YOUR DATABASE NAME> < db_generate.sql with your root password, for example on my system, I used: mysql -uroot -pnot_really_my_password mantis_db < db_generate.sql
This should return immediately with no errors.

Now we will configure Mantis:

Create a config_inc.php file for example using your favorite text editor in the <YOUR WEB ROOT>/mantis/ directory. For example, on my machine, using pico, that would be pico /var/www/html/mantis/config_inc.php

Paste the following into the file

<?php
	   	# use MD5 if you are using the default MD5 password encryption scheme
		$g_login_method = <YOUR ENCRYPTION SCHEME: MD5, PLAIN, OR CRYPT>;
		$g_hostname      = "localhost"
        $g_port          = 3306;         # 3306 is default
        $g_db_username   = "root";

		# Fill this in with your database password
        $g_db_password   = "<YOUR DATABASE PASSWORD>";
		# Fill this in with your database name
        $g_database_name = "<YOUR DATABASE NAME>"; 

		# Fill this in with your host + domain name
        $g_path          = "http://<YOUR DOMAIN NAME>/mantis/"; 
        $g_icon_path     = $g_path."images/";

		# Fill this in with your web root
        $g_absolute_path = "<YOUR WEB ROOT>/mantis/";   
        $g_use_iis = OFF;
        $g_show_version   = ON;

		# Fill this in with some email addresses
        $g_administrator_email  = "<YOUR ADMINISTRATOR EMAIL ADDRESS>"; 
        $g_webmaster_email      = "<YOUR WEB MASTER EMAIL ADDRESS>";
        $g_from_email           = "<YOUR EMAIL ADDRESS>";
        $g_to_email             = "<YOUR EMAIL ADDRESS>";
        $g_return_path_email    = "<YOUR ADMINISTRATOR EMAIL ADDRESS>";
?>

and then change the values labeled as appropriate for your installation. For example, my file looks like this:

<?php
        # use MD5 if you are using the default MD5 password encryption scheme   
        $g_login_method = MD5;
        $g_hostname      = "localhost"
        $g_port          = 3306;         # 3306 is default
        $g_db_username   = "root";
  
        # Fill this in with your database password
        $g_db_password   = "root";
        # Fill this in with your database name
        $g_database_name = "yakko1";
  
        # Fill this in with your host + domain name
        $g_path          = "http://ducky.deepdomain.com/mantis/";
        $g_icon_path     = $g_path."images/";
  
        # Fill this in with your web root
        $g_absolute_path = "/var/www/html/mantis/";
        $g_use_iis = OFF;
        $g_show_version   = ON;
        # Fill this in with some email addresses
        $g_administrator_email  = "mantis_admin@no spam . com";
        $g_webmaster_email      = "mantis_web@no spam . com";
        $g_from_email           = "mantis@no spam . com";
        $g_to_email             = "mantis@no spam . com";
        $g_return_path_email    = "mantis_admin@no spam . com";
?>

Note that the email addresses above are clearly incorrect to avoid spamming from this document - in reality, I have put valid addresses in my configuration file.
Save the configuration file.

You have now completed basic installation of Mantis - check this by opening the following url in a web bowser: http://<YOUR HOST + DOMAIN NAME>/mantis/ for example on my machine that is http://ducky.deepdomain.com/mantis/. You should see a login page. Note if you get a page full of errors that look like this:

Warning: Cannot add header information - headers already sent by (output started at /var/www/html/mantis/config_inc.php:20) in /var/www/html/mantis/core_print_API.php on line 18

Warning: Cannot add header information - headers already sent by (output started at /var/www/html/mantis/config_inc.php:20) in /var/www/html/mantis/core_print_API.php on line 20

Warning: Cannot add header information - headers already sent by (output started at /var/www/html/mantis/config_inc.php:20) in /var/www/html/mantis/core_print_API.php on line 21

It means that there are extra blank lines at the end of your config_inc.php file. Delete them & try again.

Back to contents

Securing Mantis

By default the Mantis installation creates an administrative user with the passoword root - since this is common knowledge, it is unsecure. We will create a new administrative user with a new password & then delete the default one to make your installatiuon more secure.

Create a new adminstrative user.

Open the URL: http://<YOUR HOST + DOMAIN NAME>/mantis/
Log in using the default administrator user name & root password
Click on the Manage link
Click on the Create Account link
Enter all the appropriate information for you new administrative user.
Make sure you select administrator in the Access Level menu.
Leave Enabled checked & Protected unchecked.
Hit the Create User button

If creation was successful, you will be redirected o the Manage Users page again & the botom will show 2 administrative users, which look something like:

administrator		admin		administrator		X		X		02-21 11:27		02-21 11:59		[ Edit User ]	
<YOUR ADMIN USERNAME> <YOUR ADMIN EMAIL ADDRESS> administrator X   02-21 11:59 02-21 11:59	
      [ Edit User ]

Now delete the original administrator user:

Click on the Edit User link to the right of the administrator user.
Click on the Delete User button
In the confirmation screen, click on the Delete Account button
This will log you out.

You have now successfully installed & configured Mantis - enjoy.

Back to contents

Amandeep Jawa Worker Bee Software