# Installation

This chapter explains how to install or upgrade MantisBT.

## Overview

The table below contains a high-level overview of the processes. Refer to the corresponding sections for details.

New Installation | Upgrade
Check system requirements Download and deploy MantisBT Execute the Installation script Configure the system Execute post-installation common tasks Execute post-installation specific tasks | Download and deploy MantisBT Backup your system Put the site down for maintenance Execute the Upgrade script Execute post-installation common tasks Execute post-upgrade specific tasks

## System Requirements

### Server Hardware Requirements

MantisBT has modest hardware requirements. It requires a computer that is able to run the server software.

- Server type

  The server can be a shared public web server or a dedicated co-located box.

- CPU and Memory

  As for any web application, you should size your server based on the traffic on the site.

- Disk

  The application code is less than 20 MB

  The amount of disk space required for the database will vary depending on the RDBMS and the volume of data, the main driving factor being the expected number and size of attachments.

### Server Software Requirements

All of the required software is free for commercial and non-commercial use (open source). Please refer to the table below for minimum and recommended versions.

- Operating System

  MantisBT runs on Windows, MacOS, OS/2, Linux, Solaris, the BSDs, and just about anything that supports the required server software.

- Web Server

  MantisBT is mainly tested with Microsoft IIS and Apache. However, it is expected to work with any recent web server software.

  File Extensions: MantisBT uses only .php files. If your webserver is configured for other extensions (e.g. .PHP3, .PHTML) then you will have to request the administrator to add support for .PHP files. This should be a trivial modification. Further details can be found in the PHP documentation

- PHP

  The web server must support PHP. It can be installed as CGI or any other integration technology.

- PHP extensions

  MantisBT is designed to work in as many environments as possible. Hence the required extensions are minimal and many of them are optional affecting only one feature.

  - mandatory: the extension for the RDBMS being used ( mysqli, pgsql, oci8, mssql/sqlsrv, ibm-db2 )

  - Curl - required for the Twitter integration feature

  - GD - required for the graphs feature

  - fileinfo - Guesses the MIME type of attachments

    Without this extension, file attachment previews and downloads may not work correctly as MantisBT won't be able to send the Content-Type header to a browser requesting an attachment.

    This extension is included by default from PHP version 5.3.x and above. For older versions you will need to install the fileinfo PECL extension (this requires root access to the server you're using).

- Database

  MantisBT requires a database to store its data. The supported RDBMS are MySQL, PostgreSQL, DB2, MS SQL and Oracle (experimental).

#### Versions compatibility table

Category | Package | Minimum Version | Recommended | Comments
RDBMS | MySQL | 4.1.x | 5.0.x or above | PHP extension: mysqli
PostgreSQL | 7.0 | 8.0 or above | PHP extension: pgsql
IBM DB2 |  |  | PHP extension: ibm-db2
MS SQL Server |  |  | PHP extension: mssql or sqlsrv
Oracle | 8i | 11gR2 | PHP extension: oci8
Web Server | Apache | 1.3.x | 2.2.x |
lighttpd | 1.4.x | 1.4.x |
IIS | 6.0 | 6.0 |
PHP | PHP | 5.1.x | 5.2.x or above | See above for PHP extensions

### Client Requirements

MantisBT should run on most recent browsers in the market, including but not limited to

- Firefox 3 and above

- Internet Explorer 6 and above

- Chrome

- Safari

- Opera

## Pre-installation / upgrade tasks

These tasks cover the download and deployment of MantisBT, and should be performed prior to any new installation or upgrade.

1. Download MantisBT

2. Transfer the downloaded file to your webserver

   This can be done using whatever method you like best (ftp, scp, etc). You will need to telnet/ssh into the server machine for the next steps.

3. Extract the release

   It is highly recommended to maintain a separate directory for each release. This not only avoids mismatch between versions, (files may have been added or removed) but also provides an easy path to downgrade your installation, should you need to.

   The usual command is (1 step):

       tar -xzf filename.tar.gz

   OR (2 steps):

       gunzip filename.tar.gz
       tar -xf filename.tar

   Other file archiving tools such as 7-Zip should also be able to handle decompression of the archive.

   The extraction process should create a new directory like mantisbt-1.2.x

4. Rename the directory

   For new installations, you may want to rename the directory just created to something simpler, e.g. mantisbt

       mv mantisbt-1.2.x mantisbt

## New Installation

This chapter explains how to perform a new installation of MantisBT.

Start by checking the system requirements and installing the appropriate version of required software.

Once that is done, execute the installation script. From your web browser, access

    http://yoursite/mantisbt/admin/install.php

The installation procedure will go through the following steps:

1. The script checks basic parameters for the web server

2. Provide required information for the installation

   - database type

   - database server hostname

   - user and password

     Required privileges: SELECT, INSERT, UPDATE, and DELETE

   - high-privileged database account

     Additional privileges required: INDEX, CREATE, ALTER, and DROP

     If this account is not specified, the database user will be used.

3. Click the Install/Upgrade Database button

4. The script creates the database and tables.

   The default Administrator user account is created at this stage, to allow the initial login and setup of MantisBT.

5. The script attempts to write a basic config_inc.php file to define the database connection parameters.

   This operation may fail if the web server's user account does not have write permissions to the directory (which is recommended for obvious security reasons). In this case, you will have to manually create the file and copy/paste the contents from the page.

6. The script perform post installation checks on the system.

   Review and correct any errors.

## Upgrading

This chapter explains how to upgrade an existing MantisBT installation.

Start by Performing the steps described in Pre-installation tasks above.

1. Put the site down for maintenance

       cp mantis_offline.php.sample mantis_offline.php

   This will prevent users from using the system while the upgrade is in progress.

2. Always Backup your code, data and config files before upgrading !

   This includes your Mantis directory, your attachments, and your database. Refer to the Backups section for details.

3. Copy the configuration files

   To preserve your system settings, you should copy the files listed below to the new directory, as well as any other custom files such as logo, favicon, css, etc.

   config_inc.php custom_strings_inc.php custom_constants_inc.php custom_functions_inc.php

4. Execute the upgrade script. From your web browser, access

       http://yoursite/mantisbt-NEW/admin/install.php

   where mantisbt-NEW is the name of the directory where the new release was extracted

5. Provide required information for the upgrade

   - high-privileged database account

     Additional privileges required: INDEX, CREATE, ALTER, and DROP

     If this account is not specified, the database user will be used.

6. Click the Install/Upgrade Database button

7. At the end of the upgrade, review and correct any warnings or errors.

## Configure your installation

There are many settings that you can adjust to configure and customize MantisBT. Refer to the Configuration section, as well as the config_default_inc.php file for in depth explanations of the available options. Check out also the Customizing MantisBT section for further options to personalize your installation.

This step is normally only required for new installations, but when upgrading you may want to review and possibly customize any new configuration options.

Open or create the file config_inc.php in an editor and add or modify any values as required. These will override the default values.

You may want to use the provided config_inc.php.sample file as a starting point.

WARNING: you should never edit the config_default_inc.php file directly, as it could cause issues with future upgrades.

## Post-installation and upgrade tasks

Instructions in this section are common to both new installations and upgrades, and should be applied after completing either process.

1. Test your configuration

   Load up admin/check.php to validate if everything is setup correctly.

   NOTE (for PHP 5.2 only): check.php sometimes reports the value of register_globals incorrectly. To confirm the correct value, Create a page with this line in it:

       <?php phpinfo(); ?>

   save it with a .php extension and load it up in your web browser.

2. Delete the admin folder

   For security reasons, the scripts within this directory should not be accessible on a live MantisBT site or on any installation that is accessible via the Internet.

   Once you have confirmed that the install/upgrade was successful, you should delete this directory

       rm -r admin

## Post-installation tasks

Instructions in this section should only be applied after a new installation

1. Login to your bugtracker

   Use the default Administrator account. The id and password are administrator / root.

2. Create a new Administrator account

   Go to Manage > Manage Users and create a new account with 'administrator' access level.

3. Disable or delete the default Administrator account

4. Create a new Project

   Go to Manage > Manage Projects and create a new project

## Post-upgrade tasks

Instructions in this section should only be applied after upgrading an existing installation.

1. Test the new release

   Perform any additional testing as appropriate to ensure the new version does not introduce any regressions.

2. Switch the site to the new version

   The commands below should be executed from the web root (or wherever the mantisbt scripts are installed) and assume that the "live" directory (old version) is named mantisbt and the new release directory is mantisbt-1.2.x.

       mv mantisbt mantisbt-old
       mv mantisbt-1.2.x mantisbt

3. Put the site back on line

       rm mantis_offline.php

   This should be the final step in the upgrade process, as it will let users login again.

## Backups

It is strongly recommended to backup your MantisBT database on a regular basis. The method to perform this operation depends on which RDBMS you use.

Backups are a complex subject, and the specificities of implementing and handling them for each RDBMS are beyond the scope of this document. For your convenience, the section below provides a simple method to backup MySQL databases.

You should also consider implementing backups of your MantisBT code (which includes your configs and possibly customization), as well as issue attachments (if stored on disk) and project documents.

!!! Backups should always be performed before an upgrade !!!

### MySQL Backups

MySQL databases are easy to backup using the mysqldump command:

    mysqldump -u<username> -p<password> <database name> > <output file>

To restore a backup you will need to have a clean database. Then run:

    mysql -u<username> -p<password> <database name> < <input file>

You can also perform both of these tasks using phpMyAdmin

A good idea is to make a backup script and run it regularly through cron or a task scheduler (for Windows see WinCron ). Using the current date in the filename can prevent overwriting and make cataloguing easier.

References and useful links:

- mysqlhotcopy documentation

- automysqlbackup script

## Uninstall

It is recommended that you make a backup in case you wish to use your data in the future. See the Backups page for details.

To uninstall MantisBT:

- Delete the MantisBT directory and all files and subdirectories.

- Drop all MantisBT tables from the database, these can be identified by the configured prefix for the installation. The default prefix is 'mantis'.

- Remove any customizations or additions that you may have made.

If you have the permissions to create/drop databases and you have a specific database for MantisBT that does not contain any other data, you can drop the whole database.