The guide walks a user through installing MantisBT on Ubuntu 21 in under half an hour, beginning with updating the system and pulling all required packages such as Apache, PHP, MariaDB, and unzip. It then secures MariaDB by setting a root password, removing unnecessary accounts, creating a dedicated database and user for Mantis, and explains why each permission step is critical to avoid connection errors. After downloading the latest release from GitHub, the instructions move on to configuring file ownership for Apache, enabling mod_rewrite, creating a virtual host configuration, and finishing the setup through the web installer while reminding you to delete install.php for security. The post also offers optional performance tweaks like raising PHP’s max_execution_time, highlights common pitfalls such as missing php-mysql or wrong permissions, and points users toward Apache logs for troubleshooting.

How to Install Mantis BT on Ubuntu 21

You’ll get a fresh MantisBT install in under 30 minutes, plus a few sanity‑checks that stop the most common headaches.

1. Pull the required packages into your repo

sudo apt update
sudo apt install apache2 php libapache2-mod-php php-mysql mariadb-server unzip -y

Why it matters:

apache2 and libapache2-mod-php give you a web server that understands PHP.

php-mysql is the MySQL driver MantisBT needs; without it you’ll get “Could not connect to database” errors before you even hit the login page.

mariadb-server is the default DB on Ubuntu 21, and unzip will let us extract the tarball later.

2. Secure MariaDB and create a Mantis user

sudo mysql_secure_installation

When prompted, set a root password, remove anonymous users, disallow remote root logins, delete the test database, and reload privileges.

Then log in:

sudo mysql -u root -p

Inside MySQL run:

CREATE DATABASE mantisdb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON mantisdb.* TO 'mantisuser'@'localhost' IDENTIFIED BY 'StrongPass!23';
FLUSH PRIVILEGES;
EXIT;

Why it matters:

MantisBT can only talk to a database that exists and has a user with the right permissions. Skipping this step means you’ll sit staring at “Database connection failed” for hours.

3. Grab the latest MantisBT release

cd /tmp
wget https://github.com/mantisbt/mantisbt/archive/refs/tags/release-2.28.1.zip
unzip release-2.28.1.zip
sudo mv mantisbt-release-2.28.1 /var/www/html/mantisbt

Why it matters:

By pulling from the official GitHub tag you get a clean, unmodified package. If you clone the repo or download an older tarball you might end up with deprecated files that break on Ubuntu 21’s newer PHP version.

4. Configure file permissions for Apache

sudo chown -R www-data:www-data /var/www/html/mantisbt
sudo find /var/www/html/mantisbt -type d -exec chmod 750 {} \;
sudo find /var/www/html/mantisbt -type f -exec chmod 640 {} \;

Why it matters:

Apache runs as www‑data, so the web server needs to read everything. Setting directories to 750 and files to 640 keeps your system tight without giving Apache write access where it’s not needed.

5. Enable Apache modules & rewrite rules

sudo a2enmod rewrite
sudo systemctl restart apache2

Create an Apache config for Mantis:

sudo tee /etc/apache2/sites-available/mantis.conf <<'EOF'
<VirtualHost *:80>
    DocumentRoot /var/www/html/mantisbt
    <Directory /var/www/html/mantisbt/>
        Options FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>
EOF

sudo a2ensite mantis.conf
sudo systemctl reload apache2

Why it matters:

mod_rewrite powers the friendly URLs MantisBT prefers. Without it you’ll see raw script names in your address bar, and some features won’t work.

6. Finish the setup through the web installer

Open http://your‑server-ip/mantisbt/install.php.

Fill in:

• Database type: MySQLi
• Hostname: localhost
• Username: mantisuser
• Password: StrongPass!23 (the one you set earlier)
• Database name: mantisdb

Click “Submit” and let Mantis create its tables. Once that’s done, delete the install.php file:

sudo rm /var/www/html/mantisbt/install.php

Why it matters:

Deleting install.php stops a potential security hole; if left behind anyone could re‑run the installer and overwrite your data.

7. Tweaks for performance (optional)

sudo nano /etc/php/8.1/apache2/php.ini

Find max_execution_time and bump it from 30 to 120:

max_execution_time = 120

Then restart Apache again:

sudo systemctl restart apache2

Why it matters:

Large projects with many attachments can trip the default PHP timeout. Raising it keeps bulk imports from dying mid‑way.

8. Common pitfalls I’ve seen in real life

• “Could not connect to database” after upgrading PHP – The php-mysql package isn’t automatically pulled when you add new PHP versions. Install it manually or run apt install php7.4-mysql.
• 500 errors on /install.php – This usually means the directory permissions are wrong. Re‑run step 4 and double‑check ownership.
• Blank page after login – Make sure Apache’s .htaccess is enabled (AllowOverride All). If not, Mantis can’t rewrite URLs, and you’ll hit a 404 that looks like a blank screen.

That’s it! Hit your server’s IP in a browser, log in with administrator/manager, and you’re ready to start tracking bugs. If something doesn’t work as expected, check the Apache error logs (sudo tail -f /var/log/apache2/error.log) – they’re usually more helpful than Mantis’ generic messages.