Self-Hosting MantisBT with Docker Compose

What Is MantisBT?

MantisBT started as a university project in 2000 and evolved into one of the most enduring open-source bug trackers in existence. Over two decades later, it still runs issue tracking for thousands of organizations — from small open-source projects to large enterprises. Built on PHP and MySQL, MantisBT provides multi-project issue management, custom fields, time tracking, roadmaps, and fine-grained access controls without needing a computer science degree to configure.

It replaces commercial tools like Jira, YouTrack, and Linear for teams that need straightforward bug and issue tracking without the bloat.

Quick Verdict

MantisBT is the right tool if you need a proven, low-resource bug tracker that handles multiple projects with customizable workflows. It lacks the modern UI polish of newer tools, but nothing in this space matches its stability track record or configuration depth per megabyte of RAM consumed.

Use Cases

Use Case	MantisBT Fit
Software bug tracking	Excellent — built specifically for this
Multi-project issue management	Excellent — unlimited projects, per-project configs
IT helpdesk tickets	Good — works but not purpose-built for customer-facing support
Agile/Scrum boards	Weak — no native Kanban or sprint views
Customer support	Weak — use FreeScout or Zammad instead

Prerequisites

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

Docker Compose Configuration

MantisBT has no official Docker image. The community-maintained xlrl/mantisbt image is actively updated, runs PHP 8.x with Apache, and provides proper version tags.

Create a docker-compose.yml file:

services:
  mantisbt:
    image: xlrl/mantisbt:2.28.0
    container_name: mantisbt
    restart: unless-stopped
    ports:
      - "8989:80"
    environment:
      # Set to 1 for initial setup, then change to 0
      MANTIS_ENABLE_ADMIN: "1"
      MANTIS_TIMEZONE: "UTC"
    volumes:
      # Persist configuration created by the web installer
      - mantisbt-config:/var/www/html/config
      # Persist uploaded files and custom logos
      - mantisbt-data:/var/www/html/upload
    depends_on:
      db:
        condition: service_healthy
    networks:
      - mantisbt-net

  db:
    image: mariadb:11.7
    container_name: mantisbt-db
    restart: unless-stopped
    environment:
      MARIADB_ROOT_PASSWORD: "changeme_root_password"
      MARIADB_DATABASE: "bugtracker"
      MARIADB_USER: "mantisbt"
      MARIADB_PASSWORD: "changeme_mantis_password"
    volumes:
      - mantisbt-db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - mantisbt-net

volumes:
  mantisbt-config:
  mantisbt-data:
  mantisbt-db:

networks:
  mantisbt-net:

Important: Change MARIADB_ROOT_PASSWORD and MARIADB_PASSWORD to strong, unique passwords before starting.

Start the stack:

docker compose up -d

Initial Setup

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

Field Value
Type of Database MySQL/MySQLi
Hostname db
Username mantisbt
Password The MARIADB_PASSWORD you set
Database name bugtracker
Admin Username mantisbt
Admin Password Same as above
Click Install/Upgrade Database. The installer creates all tables and populates default data.
After installation completes, log in at http://your-server-ip:8989 with the default credentials:
- Username: administrator
- Password: root
Change the admin password immediately — go to My Account → Change Password.
Disable admin access after setup by changing the environment variable:
```
MANTIS_ENABLE_ADMIN: "0"
```
Then restart:
```
docker compose up -d
```
Leaving admin access enabled is a security risk — the /admin/ directory exposes database schema tools and system information.

Field	Value
Type of Database	MySQL/MySQLi
Hostname	`db`
Username	`mantisbt`
Password	The `MARIADB_PASSWORD` you set
Database name	`bugtracker`
Admin Username	`mantisbt`
Admin Password	Same as above

Configuration

MantisBT stores configuration in /var/www/html/config/config_inc.php, which the web installer creates automatically. Key settings to customize after installation:

Email Notifications

Add SMTP configuration to send ticket notifications. In the MantisBT admin panel under Manage → Configuration:

Setting	Value	Purpose
`phpMailer_method`	`PHPMAILER_METHOD_SMTP`	Use SMTP instead of PHP mail()
`smtp_host`	Your SMTP server	Mail server hostname
`smtp_port`	`587`	TLS port (or 465 for SSL)
`smtp_username`	Your SMTP user	Authentication
`smtp_password`	Your SMTP password	Authentication
`smtp_connection_mode`	`tls`	Encryption method
`webmaster_email`	`[email protected]`	From address
`from_email`	`[email protected]`	Reply-to address

Custom Fields

MantisBT supports custom fields per project — go to Manage → Custom Fields. Field types include string, numeric, float, enumeration, email, checkbox, date, radio, and list. Each field can be assigned to specific projects with per-project visibility.

Access Levels

MantisBT uses a numeric access level system:

Level	Name	Typical Use
10	Viewer	Can view public issues only
25	Reporter	Can create issues
40	Updater	Can modify existing issues
55	Developer	Can assign and resolve issues
70	Manager	Can manage project settings
90	Administrator	Full system access

Advanced Configuration

LDAP/Active Directory

MantisBT supports LDAP authentication natively. Key configuration values (set via admin panel or config_inc.php):

$g_login_method = LDAP;
$g_ldap_server = 'ldap://your-ldap-server';
$g_ldap_root_dn = 'dc=example,dc=com';
$g_ldap_bind_dn = 'cn=admin,dc=example,dc=com';
$g_ldap_bind_passwd = 'your-bind-password';
$g_ldap_uid_field = 'uid';
$g_ldap_realname_field = 'cn';

Subprojects and Categories

MantisBT supports hierarchical project structures. Create subprojects under Manage → Projects to organize large codebases. Categories within each project further classify issues (e.g., “UI”, “Backend”, “Database”).

Source Control Integration

The Source Integration plugin (bundled) connects MantisBT to Git, SVN, and Mercurial repositories. Configure under Manage → Plugins → Source Integration. Commits referencing issue IDs (e.g., Fixed #1234) automatically attach to the corresponding issue.

Reverse Proxy

For production use, put MantisBT behind a reverse proxy with SSL. Nginx Proxy Manager example:

Field	Value
Scheme	`http`
Forward Hostname	`mantisbt` (or your server IP)
Forward Port	`8989`
Block Common Exploits	Enabled
SSL	Request a new certificate

After setting up the reverse proxy, update MantisBT’s base URL in Manage → Configuration:

$g_path = 'https://bugs.yourdomain.com/';

See Reverse Proxy Setup for detailed instructions.

Backup

MantisBT’s data lives in two places:

Database — all issues, users, projects, configurations
Uploaded files — attachments stored in /var/www/html/upload (if using disk storage) or in the database (default)

Back up the database:

docker exec mantisbt-db mariadb-dump -u mantisbt -p bugtracker > mantisbt-backup-$(date +%Y%m%d).sql

Back up the config and uploads:

docker run --rm -v mantisbt-config:/config -v $(pwd):/backup alpine \
  tar czf /backup/mantisbt-config-$(date +%Y%m%d).tar.gz /config

docker run --rm -v mantisbt-data:/data -v $(pwd):/backup alpine \
  tar czf /backup/mantisbt-uploads-$(date +%Y%m%d).tar.gz /data

See Backup Strategy for automated backup scheduling.

Troubleshooting

Admin directory shows “Access Denied”

Symptom: Navigating to /admin/install.php returns a blank page or 403 error.

Fix: Set MANTIS_ENABLE_ADMIN: "1" in your docker-compose.yml environment and restart. After completing setup, set it back to "0".

Database connection error during installation

Symptom: Installer shows “Unable to connect to the database” or “Access denied for user.”

Fix: Verify the hostname is db (the Docker service name), not localhost. Confirm the username, password, and database name match your docker-compose.yml environment variables exactly. Wait 10-15 seconds after first start for MariaDB to finish initializing.

Emails not sending

Symptom: No email notifications arrive after ticket creation or status changes.

Fix: Check SMTP settings under Manage → Configuration. Verify phpMailer_method is set to PHPMAILER_METHOD_SMTP, not PHPMAILER_METHOD_MAIL. Test with php -r "mail('[email protected]', 'Test', 'Body');" from inside the container to verify PHP mail works at all.

Uploaded files not persisting after restart

Symptom: File attachments disappear when the container restarts.

Fix: Ensure the mantisbt-data volume is mounted to /var/www/html/upload. If attachments are stored in the database (default behavior), this volume only matters for custom logos and avatars. Check $g_file_upload_method — set to DISK for file storage or DATABASE (default) for database storage.

Slow performance with large databases

Symptom: Page loads take 5+ seconds with thousands of issues.

Fix: Add indexes to frequently queried custom fields. Increase MariaDB’s innodb_buffer_pool_size — add command: --innodb-buffer-pool-size=256M to the db service. Consider upgrading to MariaDB 11.x if still on 10.x.

Resource Requirements

Resource	Minimum	Recommended
RAM	256 MB (app) + 256 MB (MariaDB)	512 MB total
CPU	1 core	2 cores
Disk	500 MB (application)	1 GB + attachments
Network	Low bandwidth	Low bandwidth

MantisBT is one of the lightest issue trackers available. The PHP + Apache process typically uses 80-150 MB, and MariaDB sits at 150-200 MB under normal load.

Verdict

If you need a bug tracker that works reliably and stays out of your way, MantisBT wins on two decades of proven stability. It handles multi-project setups, custom fields, access controls, and email notifications with under 512 MB of RAM — resources where tools like Zammad or OTOBO would barely finish loading.

The UI looks dated compared to modern alternatives. There are no Kanban boards, no real-time collaboration, and the mobile experience is basic. For customer-facing helpdesk needs, look at FreeScout or Zammad instead. But for internal issue tracking across development teams, MantisBT does exactly what it should with minimal overhead and zero surprises.

FAQ

Does MantisBT support PostgreSQL?

Yes. MantisBT supports MySQL/MariaDB, PostgreSQL, and MS SQL Server. Change the database type during installation. The Docker Compose example above uses MariaDB, but you can swap in a PostgreSQL container and select “PostgreSQL” in the installer.

Can I migrate from Jira to MantisBT?

MantisBT includes CSV import functionality under Manage → Import. Export your Jira issues to CSV, map the columns to MantisBT fields, and import. Complex workflows and custom field mappings require manual configuration after import.

Is MantisBT still actively maintained?

Yes. Version 2.28.0 was released December 30, 2025. The project has been continuously maintained since 2000 with regular security patches and feature updates. Development happens on GitHub.

How does MantisBT compare to GlitchTip?

MantisBT is a manual issue/bug tracker — humans create and manage tickets. GlitchTip is an automated error tracking system that captures exceptions from your application code via the Sentry SDK. They solve different problems. Use MantisBT for project management and bug tracking workflows; use GlitchTip for application error monitoring.

Can multiple teams use MantisBT simultaneously?

Yes. MantisBT supports unlimited projects with separate configurations, categories, custom fields, and access controls per project. Users can belong to multiple projects with different access levels in each.