Docker Compose¶

MailFallBack ships with a docker-compose.yml that defines all services. This page explains each service, its volumes, networking, and how to enable optional modules.

Services Overview¶

Core Services (always running)¶

`db` - PostgreSQL¶

db:
  image: postgres:18-alpine
  environment:
    POSTGRES_USER: ${DB_USER:-mailfallback}
    POSTGRES_PASSWORD: ${DB_PASSWORD:-mailfallback}
    POSTGRES_DB: ${DB_NAME:-mailfallback}
  volumes:
    - pgdata:/var/lib/postgresql

The PostgreSQL database stores all MFB data: users, accounts, sync jobs, audit logs, and Roundcube tables (with rc_ prefix). A healthcheck ensures dependent services wait for the database to be ready.

`mailfallback` - Web UI and API¶

mailfallback:
  build:
    context: .
    dockerfile: docker/Dockerfile
  ports:
    - "8000:8000"
  volumes:
    - dovecot_confd:/confs/dovecot
    - webmail_conf:/confs/webmail
    - maildirs:/data/mailboxes
    - maildirs2:/data/mailboxes2
  env_file: .env

The main application. On startup it:

Runs Alembic database migrations
Generates Dovecot and Roundcube configuration files into shared volumes
Ensures the default mail store and admin user exist
Starts the sync scheduler
Resumes any incomplete store migrations

`dovecot` - IMAP Server¶

dovecot:
  # pinned: 2.4.3+ replaces global ACL file with settings blocks — port mfb-acl before bumping
  image: dovecot/dovecot:2.4.2
  volumes:
    - dovecot_confd:/etc/dovecot/conf.d:ro
    - maildirs:/data/mailboxes
    - maildirs2:/data/mailboxes2
  ports:
    - "31143:31143"   # IMAP
    - "9900:9900"     # Prometheus metrics

Uses the official Dovecot 2.4 image with no custom Dockerfile. MFB writes all configuration to the dovecot_confd shared volume at boot. Dovecot reads these configs, authenticates users via SQL against the MFB database, and serves backed-up mail as read-only IMAP.

Optional Services (profiles)¶

`webmail` - Roundcube¶

webmail:
  image: roundcube/roundcubemail:latest
  ports:
    - "8001:80"
  profiles:
    - webmail

Start with:

docker compose --profile webmail up -d

Roundcube connects to Dovecot IMAP on the internal Docker network. It shares the PostgreSQL database (tables prefixed with rc_). Configuration is generated by MFB and mounted from the webmail_conf volume.

`tika` - Full-Text Search for Attachments¶

tika:
  image: apache/tika:latest
  ports:
    - "9998:9998"
  profiles:
    - tika

Start with:

docker compose --profile tika up -d

Apache Tika extracts text from attachment files (PDF, Word, Excel, etc.) so Dovecot FTS can index their content. Dovecot connects to Tika on the internal Docker network.

Starting Multiple Profiles¶

To start both optional services:

docker compose --profile webmail --profile tika up -d

Or start everything:

docker compose --profile webmail --profile tika up -d --build

Volumes¶

Volume	Purpose	Used By
`pgdata`	PostgreSQL data	`db`
`maildirs`	Primary mail storage	`mailfallback`, `dovecot`
`maildirs2`	Secondary mail storage (for multi-store setups)	`mailfallback`, `dovecot`
`dovecot_confd`	Generated Dovecot configuration	`mailfallback` (write), `dovecot` (read)
`webmail_conf`	Generated Roundcube configuration	`mailfallback` (write), `webmail` (read)

Volume persistence

Never use docker compose down -v. The -v flag deletes all volumes, destroying your mail data and database. Use docker compose down (without -v) to stop services safely.

Networking¶

All services communicate on Docker's default bridge network. No ports are exposed between containers - they use Docker DNS (service names as hostnames).

Connection	From	To	Port
Database	`mailfallback`, `dovecot`, `webmail`	`db`	5432
IMAP	`webmail`	`dovecot`	31143
Doveadm API	`mailfallback`	`dovecot`	8080
Lua userdb	`dovecot`	`mailfallback`	8000
Tika decoder	`dovecot`	`tika`	9998

Exposed Ports¶

Port	Service	Protocol	Description
8000	`mailfallback`	HTTP	Web UI and API
8001	`webmail`	HTTP	Roundcube webmail
31143	`dovecot`	IMAP	Connect with any IMAP client
9900	`dovecot`	HTTP	Dovecot Prometheus metrics
9998	`tika`	HTTP	Tika REST API

Enabling TLS for IMAP¶

By default, Dovecot runs without TLS (suitable for internal Docker networks or behind a reverse proxy). To enable IMAPS on port 31993:

Mount your TLS certificate and key into the Dovecot container. Uncomment these lines in docker-compose.yml:

volumes:
  - ./certs/tls.crt:/etc/dovecot/ssl/tls.crt:ro
  - ./certs/tls.key:/etc/dovecot/ssl/tls.key:ro

Uncomment the IMAPS port:
```
ports:
  - "31993:31993"
```
MFB generates an SSL config that enables TLS when cert files are detected. Restart to regenerate:
```
docker compose restart mailfallback dovecot
```

UID Consistency¶

All containers run as UID 1000 (user vmail). This ensures consistent file ownership across the maildirs volume, which is written to by mailfallback (via mbsync) and read by dovecot. This is important for Kubernetes deployments where containers in the same pod share a volume.

Custom Docker Compose Overrides¶

To customize the deployment without modifying docker-compose.yml, create a docker-compose.override.yml:

services:
  mailfallback:
    ports:
      - "127.0.0.1:8000:8000"  # Bind to localhost only
  dovecot:
    ports:
      - "143:31143"  # Use standard IMAP port

Apply with:

docker compose up -d

Docker Compose automatically merges docker-compose.yml with docker-compose.override.yml.