Docker Deployment¶

The complete Docker Compose setup — the compose files, startup gating, services, volumes, networks, and ports explained.

The Compose File Set¶

Mailyte does not ship a single compose file. It ships a base file plus overrides you stack on top:

# Development
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d    # ./start.sh dev

# Production
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d   # ./start.sh prod

# Cloud DB/Redis
docker compose -f docker-compose.yml -f docker-compose.cloud.yml up -d  # ./start.sh cloud

start.sh (and scripts/mailyte-ctl.sh behind it) wraps these combinations and also passes --profile console so the console behaves like any other service.

Startup Gating¶

Order is enforced with depends_on conditions, not sleep loops:

graph LR
    SC[secrets-check<br/>one-shot] --> MY[(mysql)]
    SC --> RD[(redis)]
    MY --> MG[migrate<br/>one-shot Alembic]
    MG --> PF[postfix]
    MG --> DV[dovecot]
    MG --> API[api]
    MG --> WK[worker services]
    RD --> RS[rspamd] --> PF

1. secrets-check runs first and validates the required secrets (fail-closed — a weak DB_PASSWORD stops the entire stack before a single service starts).
2. mysql boots from the secrets/db_root_password file (MYSQL_ROOT_PASSWORD_FILE, not a plain env var).
3. migrate runs alembic upgrade head once per up. Every schema-touching service waits on condition: service_completed_successfully, so a failed migration stops the deploy instead of letting a half-migrated API start.
4. Everything else starts once its dependencies are healthy.

Both one-shot containers are supposed to show Exited (0) in docker compose ps -a.

docker compose build migrate && docker compose up -d

Service Inventory¶

Container names match service names (container_name: api, postfix, ...) — except api, webhooks, and tracking in production, where fixed names are reset because they run 2 replicas.

Port Mappings (base file)¶

Host bindings from docker-compose.yml. In production, everything below the mail rows is rebound to 127.0.0.1 and reached externally only through Traefik on 443.

MySQL and Redis publish no host ports — they are reachable only on the Docker network.

Volumes and Persistent Data¶

Two kinds of persistence, and the distinction matters for backups and deploys:

Named volumes (live under /var/lib/docker/volumes)¶

With COMPOSE_PROJECT_NAME=mailyte-prod these appear as mailyte-prod_mysql_data, etc. Pinning the project name is what keeps volumes attached across release directories — see deployment/deploy.sh's header.

Bind mounts (live in the project tree)¶

# See volume sizes
docker system df -v | grep -A 25 "VOLUME NAME"

# Inspect a specific volume
docker volume inspect mailyte-prod_mysql_data

Networks¶

docker-proxy is the only container that touches /var/run/docker.sock, and it is scoped to list/inspect/restart — no exec, no images, no volumes. monitoring restarts unhealthy containers through it; cert_manager SIGHUPs postfix/dovecot after certificate rotation.

Common Operations¶

# Start everything (interactive menu with staged startup)
./start.sh

# Start / stop / status via CLI
./start.sh start
./start.sh stop
./start.sh status
./start.sh logs postfix
./start.sh health

# Or raw compose
docker compose up -d
docker compose down            # stops; keeps data
docker compose down -v         # DESTROYS named volumes (database, queue)

# Restart a single service
docker compose restart postfix

# Rebuild one service after a code change
./start.sh dev --rebuild api   # or:
docker compose build api && docker compose up -d api

# Run migrations / check status
python3 manage.py migrate
python3 manage.py migrate:status

# Enter a container
docker compose exec postfix bash
docker compose exec mysql sh -c 'mysql -u root -p"$(cat /run/secrets/db_root_password)"'

Environment Variables¶

Interpolation values come from .env (see Configuration). The essentials: