Operating System CentOS

How to Install MantisBT 2.28 on AlmaLinux 9 or Rocky Linux 9

Install MantisBT 2.28 on AlmaLinux 9 or Rocky Linux 9 with Apache, MariaDB and PHP, remove the default admin account and configure email.

MantisBT (Mantis Bug Tracker) is an open source, web-based issue tracker written in PHP. This guide installs the current stable series, MantisBT 2.28, on AlmaLinux 9 or Rocky Linux 9 with Apache, MariaDB and PHP-FPM, and covers the steps that are easy to miss afterwards: removing the installer, replacing the default administrator account and getting notification email to work. The commands also apply to CentOS Stream 9 and RHEL 9.

CentOS 7 reached end of life in June 2024 and no longer receives security updates, and MantisBT 2.5 is many releases behind. The RHEL 9 family ships everything MantisBT needs in its own repositories, so the third-party PHP and MariaDB repositories that older tutorials add are no longer necessary.

Requirements

  • A server running AlmaLinux 9 or Rocky Linux 9 with a sudo user (the examples use deploy).
  • A host name such as bugs.example.com pointing to the server.
  • MantisBT 2.28 needs PHP 7.4 or newer and has been tested with PHP releases up to 8.4, with the mysqli and mbstring extensions. MySQL and MariaDB are the recommended databases.

Install Apache, MariaDB and PHP

Update the system and install the web server and database:

sudo dnf upgrade -y
sudo dnf install -y httpd mariadb-server tar policycoreutils-python-utils

The default PHP in the RHEL 9 family is 8.0, which the PHP project no longer maintains. Newer versions are available as module streams. List them and enable the newest one offered (8.3 in this example):

dnf module list php
sudo dnf module reset -y php
sudo dnf module enable -y php:8.3

Install PHP with the extensions MantisBT uses. mysqlnd and mbstring are mandatory; gd is used for the captcha, ldap for LDAP or Active Directory logins and soap for the SOAP API. Leave out the last two if you do not need them:

sudo dnf install -y php php-mysqlnd php-mbstring php-gd php-opcache php-ldap php-soap

On this platform Apache runs PHP through PHP-FPM. Start and enable all three services:

sudo systemctl enable --now mariadb php-fpm httpd

Create the database

Secure MariaDB first and accept the script's suggestions:

sudo mariadb-secure-installation

Open the MariaDB shell:

sudo mariadb

Create the database and a user for MantisBT. Choose your own password:

CREATE DATABASE mantisbt CHARACTER SET utf8mb4;
CREATE USER 'mantisbt'@'localhost' IDENTIFIED BY 'change-this-password';
GRANT ALL PRIVILEGES ON mantisbt.* TO 'mantisbt'@'localhost';
EXIT;

The installer needs the right to create and alter tables, which ALL PRIVILEGES on this one database includes. Day-to-day operation only needs SELECT, INSERT, UPDATE and DELETE.

Download MantisBT

Stable releases are published on SourceForge and linked from the download page on mantisbt.org. At the time of writing the latest is 2.28.4; adjust the version if a newer one is listed.

cd /tmp
curl -L -o mantisbt-2.28.4.tar.gz \
  https://sourceforge.net/projects/mantisbt/files/mantis-stable/2.28.4/mantisbt-2.28.4.tar.gz/download
sudo tar -xzf mantisbt-2.28.4.tar.gz -C /var/www/
sudo mv /var/www/mantisbt-2.28.4 /var/www/mantisbt

The same SourceForge folder contains a .digests file with checksums and a PGP signature (.asc) for each archive if you want to verify the download.

The code can stay owned by root. The installer only has to write one file, config/config_inc.php, so give Apache's user temporary write access to the config directory. With SELinux enforcing, the directory also needs a writable label:

sudo chown apache:apache /var/www/mantisbt/config
sudo semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/mantisbt/config(/.*)?"
sudo restorecon -R /var/www/mantisbt

Configure Apache

Create /etc/httpd/conf.d/mantisbt.conf:

<VirtualHost *:80>
    ServerName bugs.example.com
    DocumentRoot /var/www/mantisbt

    <Directory /var/www/mantisbt>
        Options FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog logs/mantisbt_error.log
    CustomLog logs/mantisbt_access.log combined
</VirtualHost>

AllowOverride All lets the .htaccess files that ship with MantisBT take effect; they block web access to internal directories such as config and core.

Test the configuration, reload Apache and open the firewall:

sudo apachectl configtest
sudo systemctl reload httpd
sudo firewall-cmd --permanent --add-service=http --add-service=https
sudo firewall-cmd --reload

Issue reports and passwords should not travel unencrypted. Add a TLS certificate (for example with Certbot and mod_ssl) before you invite users, and use the https:// address from then on.

Run the web installer

Browse to http://bugs.example.com/admin/install.php. The first page checks the PHP setup; then fill in the database form:

  1. Type of database: MySQL Improved.
  2. Hostname: localhost.
  3. Username / Password: mantisbt and its password.
  4. Database name: mantisbt.
  5. Admin username / password: leave empty. They are only needed when the regular account lacks the rights to create tables.

Click Install/Upgrade Database. The installer creates the tables and a default administrator account and writes config/config_inc.php. If it reports that it cannot write the file, it prints the contents so you can create the file by hand.

Secure the new installation

Log in at http://bugs.example.com/ with the default account administrator and password root. These credentials are public knowledge, so deal with them before anything else:

  1. Go to Manage > Users and create your own account with the administrator access level.
  2. Log in with the new account, then disable or delete the default administrator account.

Open http://bugs.example.com/admin/check/index.php once to see MantisBT's own configuration check, then delete the admin directory. It is only needed for installation and upgrades, and leaving it reachable is a security risk:

sudo rm -r /var/www/mantisbt/admin

Take away Apache's write access to the configuration again and remove the writable SELinux label:

sudo chown -R root:apache /var/www/mantisbt/config
sudo chmod 640 /var/www/mantisbt/config/config_inc.php
sudo semanage fcontext -d "/var/www/mantisbt/config(/.*)?"
sudo restorecon -R /var/www/mantisbt

Configure email and sign-up

All local settings go in /var/www/mantisbt/config/config_inc.php; never edit config_defaults_inc.php, which is replaced on upgrade. MantisBT relies on email for password resets and notifications. Add your SMTP relay's details and your own addresses:

$g_phpMailer_method     = PHPMAILER_METHOD_SMTP;
$g_smtp_host            = 'smtp.example.com';
$g_smtp_port            = 587;
$g_smtp_connection_mode = 'tls';
$g_smtp_username        = 'mantis@example.com';
$g_smtp_password        = 'smtp-password';

$g_webmaster_email      = 'webmaster@example.com';
$g_from_email           = 'mantis@example.com';
$g_return_path_email    = 'mantis@example.com';

$g_email_send_using_cronjob = ON;
$g_allow_signup         = OFF;

Self-registration is on by default; $g_allow_signup = OFF closes it so that only administrators create accounts. Remove that line if you want public sign-up.

SELinux stops Apache and PHP-FPM from opening outbound network connections by default. Allow it so MantisBT can reach the SMTP server:

sudo setsebool -P httpd_can_network_connect 1

With $g_email_send_using_cronjob switched on (the setting MantisBT recommends), messages are queued and sent by a script instead of slowing down page loads. Create /etc/cron.d/mantisbt to run it every five minutes as the apache user:

*/5 * * * * apache /usr/bin/php /var/www/mantisbt/scripts/send_emails.php

Test by requesting a password reset for your account and checking that the message arrives.

Backups and upgrades

Back up the database regularly, and always before an upgrade, together with the config directory:

sudo mariadb-dump mantisbt > mantisbt-$(date +%F).sql
sudo tar -czf mantisbt-config-$(date +%F).tar.gz -C /var/www/mantisbt config

To upgrade, extract the new release into its own directory, copy config_inc.php and any custom files and third-party plugins from the old config and plugins directories into it, open admin/install.php of the new copy and click Install/Upgrade Database, then switch the virtual host to the new directory and delete its admin directory. The full procedure is in the MantisBT Administration Guide.

Frequently asked questions

Where are attachments stored?

In the database by default ($g_file_upload_method = DATABASE), which keeps backups to a single dump. For many or large files you can switch to DISK and set an upload folder outside the web root that apache can write to; on this platform that folder also needs the httpd_sys_rw_content_t SELinux label. The size limit is $g_max_file_size, capped by upload_max_filesize and post_max_size in /etc/php.ini.

Can I use PostgreSQL instead of MariaDB?

MantisBT supports PostgreSQL through the pgsql extension, but its documentation recommends MySQL or MariaDB because that is what the project is mainly developed and tested with.

The installer page is blank or shows PHP code. What is wrong?

PHP-FPM is not running or was installed after Apache started. Run sudo systemctl restart php-fpm httpd and check /var/log/httpd/mantisbt_error.log and /var/log/php-fpm/www-error.log.

How do I take the tracker offline during maintenance?

Copy mantis_offline.php.sample to mantis_offline.php in the MantisBT directory. While that file exists, users see a maintenance notice; delete it to bring the site back.

Share story:

Continue reading other guides on How VPS.