This chapter explains how to install or upgrade MantisBT.

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

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.

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). mbstring - Recommended for best performance with multibyte (UTF8) strings processing. Required if the admin needs to list the SQL queries generated by MantisBT (see $g_show_queries_list in ). Database MantisBT requires a database to store its data. The supported RDBMS are: MySQL (recommended), PostgreSQL, DB2, Microsoft SQL Server and Oracle (experimental). Note: There are known issues with all of the above platforms except MySQL, and to a lesser extend PostgreSQL; moreover, you should be aware that support for DB2, SQL server and Oracle is limited.

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 2005 2005 or above 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

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

These tasks cover the download and deployment of MantisBT, and should be performed prior to any new installation or upgrade. Download MantisBT 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. 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 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

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: The script checks basic parameters for the web server 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. Click the Install/Upgrade Database button 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. 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. The script perform post installation checks on the system. Review and correct any errors.

This chapter explains how to upgrade an existing MantisBT installation. Start by Performing the steps described in Pre-installation tasks above. 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. 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. 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 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 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. Click the Install/Upgrade Database button At the end of the upgrade, review and correct any warnings or errors. When processing large databases from versions older than 1.2, the upgrade script may fail during the conversion of date fields, leaving the system in an inconsistent (i.e. partially updated) state. In this case, you should simply restart the upgrade process, which will resume where it left off. Note that you may have to repeat this several times, until normal completion. Reference: MantisBT issue 12735.

There are many settings that you can adjust to configure and customize MantisBT. Refer to the Configuration section, as well as the config_defaults_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_defaults_inc.php file directly, as it could cause issues with future upgrades.

Instructions in this section are common to both new installations and upgrades, and should be applied after completing either process. 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. 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

Instructions in this section should only be applied after a new installation Login to your bugtracker Use the default Administrator account. The id and password are administrator / root. Create a new Administrator account Go to Manage > Manage Users and create a new account with 'administrator' access level. Disable or delete the default Administrator account Create a new Project Go to Manage > Manage Projects and create a new project

Instructions in this section should only be applied after upgrading an existing installation. Test the new release Perform any additional testing as appropriate to ensure the new version does not introduce any regressions. 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 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.

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 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

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.