How to Self-Host Modoboa with Docker Compose

What Is Modoboa?

Modoboa is a modular, open-source mail hosting and management platform built with Django. It bundles a web-based admin panel, webmail client, antispam filtering, and domain management into a single interface. Think of it as a self-hosted alternative to Google Workspace or Microsoft 365 email — you get full control over domains, mailboxes, aliases, and quotas. The official project is actively maintained with regular releases.

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 4 GB of RAM minimum (Postfix + Dovecot + ClamAV + SpamAssassin are memory-hungry)
• 20 GB of free disk space (mail storage grows fast)
• A domain name with DNS control (MX, SPF, DKIM, DMARC records required)
• Ports 25, 143, 465, 587, 993 available (not blocked by your hosting provider)

Important: Many VPS providers block port 25 by default to prevent spam. Check with your provider before proceeding — Hetzner, DigitalOcean, and Vultr all require support tickets to unblock it.

Docker Compose Configuration

Modoboa’s Docker setup uses the official repository’s Compose configuration. The stack includes the Modoboa API (Django backend), PostgreSQL, Redis, and RQ workers for background tasks.

Create a docker-compose.yml file:

services:
  modoboa:
    image: ghcr.io/modoboa/modoboa:2.7.2
    container_name: modoboa
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
    ports:
      - "8080:8000"
    environment:
      DB: postgres
      POSTGRES_HOST: postgres
      POSTGRES_PORT: "5432"
      POSTGRES_USER: modoboa
      POSTGRES_PASSWORD: changeme-strong-password       # CHANGE THIS
      POSTGRES_DB: modoboa
      SECRET_KEY: changeme-generate-with-openssl-rand   # CHANGE THIS — generate with: openssl rand -hex 32
      ALLOWED_HOSTS: mail.example.com                   # CHANGE THIS to your domain
      REDIS_URL: redis://redis:6379/0
      LANG: en_US.UTF-8
    volumes:
      - modoboa-media:/srv/modoboa/media
      - modoboa-mail:/srv/mail
    networks:
      - modoboa-net

  postgres:
    image: postgres:16-alpine
    container_name: modoboa-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: modoboa
      POSTGRES_PASSWORD: changeme-strong-password       # Must match above
      POSTGRES_DB: modoboa
    volumes:
      - modoboa-db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U modoboa"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - modoboa-net

  redis:
    image: redis:7-alpine
    container_name: modoboa-redis
    restart: unless-stopped
    volumes:
      - modoboa-redis:/data
    networks:
      - modoboa-net

  rq-worker:
    image: ghcr.io/modoboa/modoboa:2.7.2
    container_name: modoboa-worker
    restart: unless-stopped
    command: python manage.py rqworker modoboa
    depends_on:
      - modoboa
    environment:
      DB: postgres
      POSTGRES_HOST: postgres
      POSTGRES_PORT: "5432"
      POSTGRES_USER: modoboa
      POSTGRES_PASSWORD: changeme-strong-password
      POSTGRES_DB: modoboa
      SECRET_KEY: changeme-generate-with-openssl-rand
      REDIS_URL: redis://redis:6379/0
    networks:
      - modoboa-net

volumes:
  modoboa-db:
  modoboa-media:
  modoboa-mail:
  modoboa-redis:

networks:
  modoboa-net:

Start the stack:

docker compose up -d

Note: Modoboa manages the web admin and mailbox configuration. You still need Postfix (SMTP) and Dovecot (IMAP) running separately — either on the host or in additional containers. See the mail delivery configuration section below.

Initial Setup

1. Wait for the containers to start (check with docker compose logs -f modoboa)
2. Run the initial deployment command:

docker compose exec modoboa python manage.py migrate
docker compose exec modoboa python manage.py createsuperuser

3. Open http://your-server-ip:8080 in your browser
4. Log in with the superuser account you created
5. Navigate to Domains → Add domain to add your mail domain
6. Create mailboxes under the domain

Configuration

DNS Records

Before your mail server can send and receive email, configure these DNS records:

Record	Type	Value
MX	MX	mail.example.com (priority 10)
SPF	TXT	v=spf1 mx -all
DKIM	TXT	Generated by Modoboa (Admin → DKIM)
DMARC	TXT	v=DMARC1; p=quarantine; rua=mailto:[email protected]
Reverse DNS	PTR	mail.example.com (set via VPS provider)

Mail Delivery Setup

Modoboa handles the admin interface and webmail. For actual mail delivery, you need Postfix and Dovecot. The recommended approach is to use the modoboa-installer on the host, which configures Postfix, Dovecot, Amavis, SpamAssassin, and ClamAV alongside Modoboa.

If you prefer a fully Dockerized mail stack, consider Mailcow or Mailu instead — they bundle all mail components in a single Compose file.

Key Environment Variables

Variable	Purpose	Default
SECRET_KEY	Django secret key (cryptographic operations)	None — must set
ALLOWED_HOSTS	Comma-separated list of allowed hostnames	*
DB	Database backend (postgres or mysql)	postgres
POSTGRES_HOST	PostgreSQL hostname	localhost
REDIS_URL	Redis connection URL	redis://localhost:6379/0

Reverse Proxy

Place Modoboa behind a reverse proxy with SSL. Example Nginx Proxy Manager configuration:

• Domain: mail.example.com
• Forward Hostname/IP: modoboa (container name)
• Forward Port: 8000
• SSL: Request a new SSL certificate

For other reverse proxy options, see our Reverse Proxy Setup guide.

Backup

Back up these volumes:

Volume	Contents
modoboa-db	PostgreSQL database (accounts, domains, settings)
modoboa-mail	Email messages
modoboa-media	Uploaded attachments and media

# Database backup
docker compose exec postgres pg_dump -U modoboa modoboa > modoboa-backup.sql

# Volume backup
docker run --rm -v modoboa-mail:/data -v $(pwd):/backup alpine tar czf /backup/modoboa-mail.tar.gz -C /data .

For a comprehensive backup strategy, see our Backup Strategy guide.

Troubleshooting

Modoboa won’t start — database connection refused

Symptom: django.db.utils.OperationalError: could not connect to server Fix: Ensure PostgreSQL is healthy before Modoboa starts. The depends_on with condition: service_healthy in the Compose file handles this. If the issue persists, check that POSTGRES_HOST, POSTGRES_USER, and POSTGRES_PASSWORD match between services.

Emails not sending — port 25 blocked

Symptom: Postfix logs show connection timeouts on outbound SMTP. Fix: Most VPS providers block port 25 by default. Contact your provider’s support to request unblocking. Hetzner requires a support ticket; DigitalOcean and Vultr have similar processes.

DKIM verification failing

Symptom: Outbound emails fail DKIM checks at recipients. Fix: Generate DKIM keys in the Modoboa admin panel (Domains → your domain → DKIM). Copy the public key to a DNS TXT record at default._domainkey.example.com. Allow 24–48 hours for DNS propagation.

High memory usage from ClamAV

Symptom: Server runs out of RAM after enabling antivirus scanning. Fix: ClamAV uses 1–2 GB of RAM for virus definitions. On servers with less than 4 GB total RAM, disable ClamAV and rely on SpamAssassin alone. Alternatively, use the clamd service with ConcurrentDatabaseReload no to reduce peak memory.

Resource Requirements

• RAM: 2 GB minimum (Modoboa + PostgreSQL + Redis). 4 GB recommended if using ClamAV.
• CPU: Low for small deployments (<100 mailboxes). Medium for antispam processing.
• Disk: 10 GB for application, plus 1 GB per active mailbox (varies with email volume).

Verdict

Modoboa is a competent email administration platform with a modern web interface, but it’s not a complete Docker mail server in the way Mailcow or Mailu are. Modoboa handles the admin panel, webmail, and mailbox management — you still need to configure Postfix and Dovecot separately for mail delivery.

For most self-hosters, Mailcow is the better choice — it bundles everything (SMTP, IMAP, antispam, webmail, admin) in a single Docker Compose file. Choose Modoboa if you need its specific modular architecture, its Django-based extensibility, or if you already run Postfix and Dovecot and want a modern admin UI on top.

Related

• Modoboa vs Mailcow: Which Mail Server to Self-Host?
• How to Self-Host Mailcow with Docker Compose
• How to Self-Host Mailu with Docker
• How to Self-Host Stalwart Mail Server
• Mailu vs Mailcow: Which Mail Server to Self-Host?
• Best Self-Hosted Email Servers
• Self-Hosted Alternatives to Gmail
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy