2.5. Upgrading

⁠2.5. Upgrading

This chapter explains how to upgrade an existing MantisBT installation.

Start by Performing the steps described in Section 2.3, “Pre-installation / upgrade 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 Section 2.10, “Backups” for details.
Copy the configuration files
To preserve your system settings, you should copy the files listed below to subdirectory config of the new installation.
- config_inc.php,
- custom_strings_inc.php,
- custom_constants_inc.php and
- custom_functions_inc.php.
Note
The above list is not exhaustive. You might also have to copy other custom files specific to your installation such as logo, favicon, css, etc.
Copy third party plugins
To maintain system functionality, you should copy any additional plugins in the plugins subdirectory.
For example on Unix, you could use the following command; it will copy all installed plugins (in local subdirectories or symlinked), excluding bundled ones.
```
cd /path/to/mantisbt-OLD/plugins
find -maxdepth 1 ! -path . -type d -o -type l |
    grep -Pv "(Gravatar|MantisCoreFormatting|MantisGraph|XmlImportExport)" |
    xargs -Idirs cp -r dirs /path/to/mantisbt-NEW/plugins
```
Warning
Make sure that you do not overwrite any of the bundled plugins as per the list below, with an older version.
- Avatars via Gravatar (Gravatar)
- MantisBT Formatting (MantisCoreFormatting)
- Mantis Graphs (MantisGraph)
- Import/Export issues (XmlImportExport)
Execute the upgrade script. From your web browser, access
```
https://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.

Upgrading large databases

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.