Mantis bug tracker installation

From gvSIG CE Wiki

Jump to: navigation, search

MantisBT is an easy-to-use yet powerful bug tracking software. The gvSIG CE instance of Mantis also provides bug tracking services for the SEXTANTE GIS project.

This page documents the MantisBT installation on http://gvsigce.sourceforge.net/mantis.

Contents

Installation

The version documented here is 1.2.5 (Download).

This documentation contains a full protocol of all installation steps. This information can be used to understand and replicate the installation in case of problems. There are no passwords or other confidential information on this page. Never publish sensitive information on our Wiki!. If you wish to take over administrative tasks for gvSIG CE, contact one of our project members directly.

Command line work

Important: Make sure to read our page on Working with Project Web before attempting to replicate the steps described here.

The mantis installation lives in /home/project-web/gvsigce/htdocs.

Change to the SF.net project directory, then download and uncompress the software:

 cd /home/project-web/gvsigce/htdocs
 wget -c http://downloads.sourceforge.net/project/mantisbt/mantis-stable/1.2.5/mantisbt-1.2.5.tar.gz?r=http%3A%2F%2Fsourceforge.net%2Fprojects%2Fmantisbt%2Ffiles%2Fmantis-stable%2F1.2.5%2F&ts=1307727388&use_mirror=freefr
 tar -xzvf mantisbt-1.2.5.tar.gz

Set a symbolic link to the Mantis files and change into the new directory:

 ln -s mantisbt-1.2.5 mantis
 cd mantis

In the following, this directory will be referred to as the Mantis root dir(ectory). All shell commands printed here assume that the current working directory is the Mantis root dir.

Web based configuration

Start the web based configuration by browsing to http://gvsigce.sourceforge.net/mantis.

In the screen that now comes up, configure the database connection:

 Type of database = MySql (default)
 Hostname (for Database Server) = mysql-o
 Username (for Database) = [MySQL admin name] 
 Password (for Database) = [MySQL admin pwd]
 Databasename (for Database) = [MySQL_prefix]_mantis
 Admin Username (to create Database if required) = [MySQL admin name] 
 Admin Password (to create Database if required) = [MySQL admin pwd] 

Then click "Install/Upgrade Database"

Note: For some reason, the database creation may fail. If so, just create a new database named [MySQL_prefix]_mantis manually (e.g. using the MySQL web frontend. Then click "Retry" to complete the database setup.

At the bottom of the installation log window, there will be a message that it was not possible to write the settings to config_inc.php. This is a file system permission problem.

Instead, just copy config_inc.php.sample and adjust the database settings:

 cp config_inc.php.sample config_inc.php

Then insert the correct database settings:

 # --- Database Configuration ---
 $g_hostname = 'mysql-o';
 $g_db_type = 'mysql';
 $g_database_name = '[MySQL_prefix]_mantis';
 $g_db_username = '[MySQL admin name]';
 $g_db_password = [MySQL admin pwd];

Now click "Continue" to log into Mantis.

Note: Make sure that there are no blank lines in the configuration file, otherwise there will be a whitespace related error message.

Configuration

Right after the installation, Mantis includes a default account "administrator" with default password "root". That password must be changed right after the first login!

Then logout again and remove the admin folder from the Mantis root dir:

 rm admin -rf

Next time you browse to the Mantis web page, you will be presented with a login screen and there should be no warnings:

The main application configuration is in config_inc.php. Edit it to tune some settings.

General settings

Disable session validation (gets rid of annoying error messages):

 # --- Session Management ---
 $g_session_validation = OFF;

Outgoing email

Set up the outgoing email (SMTP with TLS on port 25):

 # --- Email Configuration ---
 #$g_administrator_email  = 'noreply@gvsigce.net';
 #$g_webmaster_email      = 'noreply@gvsigce.net';
 #$g_from_email           = 'gvsigce@users.sourceforge.net';# the "From: " field in emails
 #$g_return_path_email    = 'gvsigce@users.sourceforge.net';# the return address for bounced mail
 $g_enable_email_notification = ON;
 $g_phpMailer_method	= PHPMAILER_METHOD_SMTP;
 $g_smtp_host		= 'prwebmail';
 $g_smtp_port		= 25;
 $g_smtp_connection_mode = 'tls';
 $g_smtp_username	= 'gvsigce';
 $g_smtp_password	= [SF.net project email password];
 $g_from_name		= 'gvSIG CE Bug Tracker';
 $g_email_receive_own	= OFF;
 $g_email_send_using_cronjob = OFF;

Logo and branding

Configure the logo for the page headers: simply upload a new logo GIF into "images/", then make the settings accordingly:

 # --- Branding ---
 $g_window_title		= 'gvSIG CE: Bug Tracker (MantisBT)';
 $g_page_title			= 'gvSIG CE Bug Tracker on MantisBT';
 $g_logo_image			= 'images/gvsigce_mantis_logo.gif';
 $g_favicon_image		= 'images/favicon.ico';

(upload a customized 16x16 favicon.ico as well, for the web browser to dispay in its tab/window)

Uploads

Set the maximum size for file uploads (attachments to tickets). The following controls the upload settings:

 $g_allow_file_upload	= ON;
 $g_file_upload_method	= DATABASE; # or DISK
 $g_absolute_path_default_upload_folder = ; # used with DISK, must contain trailing \ or /.
 $g_max_file_size		= 2000000;	# in bytes (currently ca. 8 MB; MySQL max_allowed_packet)
 $g_preview_attachments_inline_max_size = 256 * 1024;
 $g_allowed_files		= ;		# extensions comma separated, e.g. 'php,html,java,exe,pl'
 $g_disallowed_files		= ;		# extensions comma separated

Note: By default, uploads are stored as BLOBs in the MySQL database. In this case, the upper limit for the upload size is MySQL's max_allowed_packet site. This is a server variable that can be checked using phpMyAdmin (check the "Variables" page).

Although the server settings for SF.net's MySQL service seem to allow a maximum size of 8MB, there are other PHP variables set on SF.net, which introduce an even lower limit (upload_max_file_size and post_max_size). In effect, $g_max_file_size cannot be set higher than ca. 2000000 bytes (2MB).

Permissions

By default, users need to register before even being allowed to view bug tickets or roadmaps. In order to allow the public read-only access to these resources, a guest account is needed. E.g. log in as administrator and create a new account "guest". Leave the real name blank, and provide a fake email. Make sure that the account's role is set to VIEWER (!).

Then turn on anonymous log-in and use the "guest" account for that purpose:

 # --- Anonymous Access / Signup ---
 $g_allow_signup			= ON;
 $g_allow_anonymous_login	= ON;
 $g_anonymous_account		= 'anonymous';

Also, allow anonymous viewing access to the roadmap page:

 $g_roadmap_view_threshold = VIEWER;

PHP customization

Add the SF.net logo to the Mantis footer. Download the SF.net logo GIF to the "images" directly of the Mantis root dir (in this case, I assume you picked sf_120x30_silver.gif).

Then edit the file core/html_api.php. Find the line that adds the logo to the page layout (ca. line 101). It should read something like this:

 echo '<a href="http://www.mantisbt.org" title="Free Web Based Bug Tracker"><img src="' . helper_mantis_url( 'images/mantis_logo_button.gif' ) . '" width="88" height="35" alt="Powered by Mantis Bugtracker" border="0" /></a>';

Simply add another line, directly above it, that reads something like this:

 echo '<a href="http://sourceforge.net" title="Open Source Web Hosting"><img src="' . helper_mantis_url( 'images/sf_120x30_silver.gif' ) . '" width="120" height="35" alt="Hosted by Sourceforge.net" border="0" /></a>';

Usage hints

The following error appears sporadically:

 "APPLICATION WARNING #2702: Your session has become invalidated". 

The "fix" is to clear your browser cache.