Skip to content
MantisDocs

Docker Compose Installation

Docker Compose Installation

Section titled “Docker Compose Installation”

This guide covers installing Mantis using Docker Compose.

Prerequisites

Section titled “Prerequisites”
  • Docker 24.0+
  • Docker Compose 2.20+
  • Git

Quick Start

Section titled “Quick Start”

1. Clone the Repository

Section titled “1. Clone the Repository”
Terminal window
git clone https://github.com/MantisPlatform/mantis.git
cd mantis

2. Configure Environment

Section titled “2. Configure Environment”
Terminal window
# Copy the example environment file
cp .env.example .env


# Edit configuration
nano .env

3. Generate Certificates

Section titled “3. Generate Certificates”
Terminal window
# Generate development certificates
just dev-certs

4. Start Services

Section titled “4. Start Services”
Terminal window
# Start all services
./docker.sh start


# Or using just
just docker-start

5. Run Database Migrations

Section titled “5. Run Database Migrations”
Terminal window
./docker.sh db-migrate

6. Access Lens

Section titled “6. Access Lens”

Open https://localhost:5173 in your browser.

Default credentials:

Docker Compose Profiles

Section titled “Docker Compose Profiles”

Mantis uses Docker Compose profiles for different deployment scenarios:

ProfileDescriptionCommand
defaultCore servicesdocker compose up
devDevelopment tools (PgAdmin, etc.)docker compose --profile dev up
uiInclude Lens UIdocker compose --profile ui up
with-clientInclude Tarsus agentdocker compose --profile with-client up
multi-thoraxMultiple Thorax instancesdocker compose --profile multi-thorax up

Service Management

Section titled “Service Management”

View Status

Section titled “View Status”
Terminal window
./docker.sh status
# or
docker compose ps

View Logs

Section titled “View Logs”
Terminal window
# All services
./docker.sh logs


# Specific service
./docker.sh logs mandible

Restart Services

Section titled “Restart Services”
Terminal window
./docker.sh restart

Stop Services

Section titled “Stop Services”
Terminal window
./docker.sh stop

Configuration

Section titled “Configuration”

Key Environment Variables

Section titled “Key Environment Variables”
Terminal window
# Database
POSTGRES_USER=mantis
POSTGRES_PASSWORD=<strong-password>
POSTGRES_DB=mantis


# JWT (RS256 — generated by just dev-certs)
# Container-internal paths (the host ./.keys/ dir is mounted at /etc/mantis/keys/)
MANDIBLE__JWT__PRIVATE_KEY_PATH=/etc/mantis/keys/jwt-private.pem
MANDIBLE__JWT__PUBLIC_KEY_PATH=/etc/mantis/keys/jwt-public.pem


# Encryption
MANTIS_ENCRYPTION_KEY=<32-byte-base64-key>

See Environment Variables for complete reference.

Health Checks

Section titled “Health Checks”

Verify services are healthy:

Terminal window
./docker.sh health

Or check individual endpoints:

Terminal window
# Mandible API
curl https://localhost:3000/api/v1/health


# Thorax (gRPC health)
grpcurl -insecure localhost:50051 grpc.health.v1.Health/Check

Troubleshooting

Section titled “Troubleshooting”

Services Won’t Start

Section titled “Services Won’t Start”
  1. Check Docker daemon is running
  2. Verify ports are available
  3. Check logs: ./docker.sh logs

Database Connection Issues

Section titled “Database Connection Issues”
  1. Verify PostgreSQL is healthy
  2. Check DATABASE_URL configuration
  3. Ensure migrations have run

Certificate Errors

Section titled “Certificate Errors”
  1. Regenerate certificates: just dev-certs
  2. Verify certificate paths in .env
  3. Check certificate validity dates

Next Steps

Section titled “Next Steps”