How to Self-Host MantisBT with Docker Compose

Docker Compose Configuration

Skip straight to the setup — MantisBT is a PHP bug tracker that’s been around since 2000 and still works well for teams that want issue tracking without the complexity of Jira or the overhead of modern project management tools.

Create a docker-compose.yml:

services:
  mantisbt:
    image: xlrl/mantisbt:2.28.0
    restart: unless-stopped
    ports:
      - "8989:80"
    environment:
      MANTIS_TIMEZONE: "UTC"              # Set to your timezone
      MANTIS_ENABLE_ADMIN: "1"            # Required for initial setup — disable after
      PHP_MAX_UPLOAD_SIZE: "10M"          # Max file attachment size
    volumes:
      - mantis-config:/var/www/html/config    # MantisBT configuration
      - mantis-custom:/var/www/html/custom    # Custom files and plugins
    depends_on:
      db:
        condition: service_healthy

  db:
    image: mariadb:11
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: changeme_root_password    # Change this
      MYSQL_DATABASE: bugtracker
      MYSQL_USER: mantisbt
      MYSQL_PASSWORD: changeme_mantis_password       # Change this
    volumes:
      - mariadb-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mariadb-admin", "ping", "-h", "localhost", "-u", "root", "-p$$MYSQL_ROOT_PASSWORD"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  mantis-config:
  mantis-custom:
  mariadb-data:

Start the stack:

docker compose up -d

What Is MantisBT?

MantisBT (Mantis Bug Tracker) is one of the oldest open-source issue trackers still in active development. It handles bug reports, feature requests, and task tracking with a web interface that prioritizes function over form. It supports multiple projects, custom fields, email notifications, role-based access control, and a plugin system.

MantisBT isn’t flashy. It doesn’t have Kanban boards, sprint planning, or time tracking built in. What it does have is 25 years of stability, a tiny resource footprint, and a straightforward PHP+MySQL architecture that practically anyone can maintain.

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 512 MB of RAM
• 2 GB of free disk space
• A domain name (optional, for remote access)

Initial Setup

1. Open http://your-server-ip:8989/admin/install.php in your browser
2. Fill in the database connection details:

Field	Value
Type of Database	MySQL/MySQLi
Hostname	db
Username	mantisbt
Password	Your MYSQL_PASSWORD value
Database name	bugtracker
Admin Username	root
Admin Password	Your MYSQL_ROOT_PASSWORD value

3. Click Install/Upgrade Database
4. After installation succeeds, log in at http://your-server-ip:8989 with:
   • Username: administrator
   • Password: root
5. Immediately change the admin password under Manage → My Account

After setup, disable the admin directory by changing the environment variable:

environment:
  MANTIS_ENABLE_ADMIN: "0"    # Disable admin installer

Then restart:

docker compose restart mantisbt

Configuration

Essential Post-Install Settings

Navigate to Manage → Manage Configuration and review these settings:

Setting	Recommended Value	Why
$g_crypto_master_salt	Random 16+ char string	Required for security — MantisBT warns if empty
$g_default_timezone	Your timezone	Matches MANTIS_TIMEZONE
$g_path	http://your-domain/	Base URL for links in emails
$g_default_language	english	UI language

Set the crypto salt by editing the config file inside the container:

docker compose exec mantisbt bash -c 'echo "\$g_crypto_master_salt = \"$(openssl rand -hex 16)\";" >> /var/www/html/config/config_inc.php'

Email Notifications

MantisBT sends email notifications for issue updates. Add SMTP settings to config_inc.php:

docker compose exec mantisbt bash -c 'cat >> /var/www/html/config/config_inc.php << "EOF"
$g_phpMailer_method = PHPMAILER_METHOD_SMTP;
$g_smtp_host = "smtp.example.com";
$g_smtp_port = 587;
$g_smtp_connection_mode = "tls";
$g_smtp_username = "[email protected]";
$g_smtp_password = "your-smtp-password";
$g_webmaster_email = "[email protected]";
$g_from_email = "[email protected]";
$g_return_path_email = "[email protected]";
EOF'

Restart the container after config changes:

docker compose restart mantisbt

File Attachments

The default PHP upload limit is 2 MB. Set PHP_MAX_UPLOAD_SIZE in the compose file for larger attachments. Also update MantisBT’s limit in config_inc.php:

$g_max_file_size = 10485760;  // 10 MB in bytes

Custom Fields

MantisBT supports custom fields per project. Navigate to Manage → Manage Custom Fields to create text, dropdown, date, or checkbox fields. Attach them to specific projects as needed.

Advanced Configuration

LDAP Authentication

For Active Directory or LDAP integration, add to config_inc.php:

$g_login_method = LDAP;
$g_ldap_server = "ldap://your-ldap-server";
$g_ldap_root_dn = "dc=example,dc=com";
$g_ldap_organization = "";
$g_ldap_protocol_version = 3;
$g_ldap_bind_dn = "cn=admin,dc=example,dc=com";
$g_ldap_bind_passwd = "your-bind-password";
$g_use_ldap_email = ON;

Plugins

MantisBT has a plugin system. Popular plugins include Source Integration (Git/SVN commit linking), Slack Integration, and dark theme. Install by extracting plugin files to the custom volume mount.

Reverse Proxy

MantisBT runs on port 80 inside the container, mapped to host port 8989. Point your reverse proxy at port 8989. Update $g_path in the config to your public URL:

$g_path = "https://bugs.example.com/";

For general reverse proxy setup, see our Reverse Proxy guide.

Backup

Back up the MariaDB database and the config volume:

# Database backup
docker compose exec db mariadb-dump -u root -p bugtracker > mantisbt_backup.sql

# Config backup
docker run --rm -v mantisbt_mantis-config:/data -v $(pwd):/backup alpine \
  tar czf /backup/mantis-config.tar.gz -C /data .

For a comprehensive backup strategy, see our Backup guide.

Troubleshooting

”Access denied” After Disabling Admin

Symptom: Can’t access /admin/install.php to fix database issues.

Fix: Set MANTIS_ENABLE_ADMIN: "1" in the compose file and restart. The admin directory is permission-locked unless this env var is set.

CAPTCHA Not Displaying

Symptom: CAPTCHA images on the login page show as broken images.

Fix: The xlrl/mantisbt image includes GD with JPEG and FreeType support. If CAPTCHA still fails, check PHP error logs:

docker compose logs mantisbt | grep -i "gd\|captcha"

Email Notifications Not Sending

Symptom: Issue updates don’t trigger emails.

Fix: Verify SMTP settings in config_inc.php. Test with MantisBT’s built-in email test (Manage → Manage Configuration → Email). Check that your SMTP server accepts connections from the container’s IP.

Database Connection Errors After Restart

Symptom: “Unable to connect to database” after container restart.

Fix: Check that the db container is healthy before MantisBT starts. The depends_on with health check in the compose file handles this. If the issue persists, verify credentials match between the compose environment and config_inc.php.

Resource Requirements

Resource	Minimum	Recommended
RAM	128 MB (app) + 128 MB (MariaDB)	512 MB total
CPU	1 core	1 core
Disk	500 MB	2 GB (scales with attachments)

MantisBT is extremely lightweight. The PHP application uses minimal RAM, and MariaDB’s footprint depends primarily on the number of issues and attachment storage.

Verdict

MantisBT is the right tool for teams that want simple, reliable bug tracking without project management overhead. It won’t replace Jira for agile workflows or Linear for modern development teams, but it handles issue tracking with less complexity than either.

For customer-facing helpdesk needs, look at FreeScout or Zammad instead. For internal bug tracking and feature request management where stability matters more than aesthetics, MantisBT’s 25-year track record speaks for itself.

FAQ

Is MantisBT still actively maintained?

Yes. Version 2.28.0 was released in late 2025. Development continues on GitHub with regular patch releases. The project has been active since 2000.

Can MantisBT handle multiple projects?

Yes. MantisBT supports unlimited projects with per-project custom fields, categories, and access control. Users can be assigned different roles per project.

How does MantisBT compare to Gitea/Forgejo issues?

MantisBT is a dedicated bug tracker with features like custom fields, email integration, and reporting. Gitea and Forgejo include issue tracking as part of a code hosting platform. If you already use Gitea/Forgejo, their built-in issues may be sufficient. MantisBT is better for non-developer teams or when issues need to be separate from code repositories.

Does MantisBT have an API?

Yes. MantisBT includes a SOAP API and a REST API (since v2.0). Both support creating, reading, updating, and deleting issues programmatically.

Related

• How to Self-Host FreeScout
• How to Self-Host Zammad
• FreeScout vs Zammad
• Self-Hosted Alternatives to Zendesk
• Best Self-Hosted Helpdesk Software
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy