How mailcow/mailcow-dockerized works
Purpose and Deployment Entry Points
mailcow: dockerized is a self-hosted mail-server stack packaged as coordinated Docker Compose services. Operational entry points are docker-compose.yml, initial environment/config generation via generate_config.sh, lifecycle/update automation in update.sh, and cold-standby provisioning through create_cold_standby.sh.
Compose-Orchestrated Service Boundary
docker-compose.yml is the system integration boundary: it wires separately built mail, web, storage, security, DNS, certificate, and operations containers. Service images are defined under data/Dockerfiles/; optional deployment topology/features are supplied as Compose overrides under helper-scripts/docker-compose.override.yml.d/, including HAProxy, external DNS/MySQL socket, and Prometheus exporter variants.
Mail Transport and Delivery Pipeline
Inbound/outbound SMTP traffic is handled by Postfix, with its container startup and transport behavior in data/Dockerfiles/postfix/docker-entrypoint.sh and data/Dockerfiles/postfix/postfix.sh; base MTA policy is in data/conf/postfix/main.cf. Mail passes through Rspamd-based filtering and ClamAV scanning before Dovecot mailbox storage/access. TLS-policy support is separated into data/Dockerfiles/postfix-tlspol/.
Mailbox, Groupware, and Data Services
Dovecot provides IMAP/mailbox functions, Sieve-related processing, quota/quarantine notifications, and maintenance jobs; its runtime boundary begins at data/Dockerfiles/dovecot/docker-entrypoint.sh and configuration is rooted at data/conf/dovecot/dovecot.conf. SOGo supplies groupware/webmail integration via data/Dockerfiles/sogo/docker-entrypoint.sh and data/conf/sogo/sogo.conf. MySQL configuration and initialization assets reside in data/conf/mysql/my.cnf and data/assets/mysql/docker-entrypoint.sh; Redis configuration is under data/conf/redis/.
Filtering, DNS, Certificates, and Network Enforcement
Rspamd is the central spam-policy engine, configured through data/conf/rspamd/rspamd.conf.local and rule fragments such as data/conf/rspamd/local.d/actions.conf; dynamic maps bridge filtering decisions to PHP-backed administrative data. Unbound provides internal DNS resolution (data/Dockerfiles/unbound/docker-entrypoint.sh, data/conf/unbound/unbound.conf). ACME certificate acquisition/renewal is encapsulated by data/Dockerfiles/acme/obtain-certificate.sh. Network enforcement is delegated to a privileged netfilter service supporting iptables/nftables in data/Dockerfiles/netfilter/main.py.
Web Administration and API Control Plane
Nginx fronts the PHP-FPM application; templated proxy configuration is in data/conf/nginx/templates/nginx.conf.j2, with container bootstrap at data/Dockerfiles/nginx/bootstrap.py. The PHP application serves administrator, domain-admin, and user interfaces from data/web/, with shared initialization/database access in data/web/inc/init_db.inc.php. Its primary machine interface is data/web/json_api.php, documented by data/web/api/openapi.yaml; OAuth endpoints are under data/web/oauth/.
Operations, Docker Control, and Extensibility
The Docker API service (data/Dockerfiles/dockerapi/main.py) exposes controlled container operations to the management plane, while Watchdog performs service/DNS/database health checks through data/Dockerfiles/watchdog/watchdog.sh. Backup is a dedicated container defined by data/Dockerfiles/backup/Dockerfile, with operator workflows in helper-scripts/backup_and_restore.sh. Administrators can inject runtime extensions through service-specific hook directories under data/hooks/, avoiding direct modification of container images or base configuration.
Main entry points: docker-compose.yml Docker Compose · index.php PHP administration · postfix/docker-entrypoint.sh Postfix · mysql/docker-entrypoint.sh MySQL
Components 23
Deployment & Operations
- Docker Compose · Integration boundary for all stack containers.
docker-compose.yml - Config generator
generate_config.sh - Update automation
update.sh - Cold standby
create_cold_standby.sh - Compose overrides · Optional HAProxy, external-service, and Prometheus topologies.
helper-scripts/docker-compose.override.yml.d/BUILD_FLAGS/docker-compose.override.yml - Watchdog · Checks service, DNS, and database health.
data/Dockerfiles/watchdog/watchdog.sh - Backup service
data/Dockerfiles/backup/Dockerfile - Runtime hooks · Service-specific operator extensions without image changes.
data/hooks/README.md
Mail Processing
- Postfix · Handles inbound and outbound SMTP transport.
data/Dockerfiles/postfix/docker-entrypoint.sh - Rspamd · Applies filtering policy and administrative data-backed maps.
data/conf/rspamd/rspamd.conf.local - ClamAV
data/Dockerfiles/clamd/clamd.sh - TLS policy
data/Dockerfiles/postfix-tlspol/docker-entrypoint.sh
Mailbox & Application Data
Web Control Plane
- Nginx · Fronts the PHP administration application.
data/Dockerfiles/nginx/bootstrap.py - PHP administration · Serves administrator, domain-admin, and user interfaces.
data/web/index.php - JSON API & OAuth · Programmatic management and OAuth endpoints.
data/web/json_api.php - Docker API · Provides controlled container operations to management services.
data/Dockerfiles/dockerapi/main.py
Connections 26
- Config generator → Docker Compose: generates environment for
- Update automation → Docker Compose: updates
- Cold standby → Docker Compose: provisions
- Compose overrides → Docker Compose: extends
- Docker Compose → Postfix: orchestrates
- Docker Compose → Dovecot: orchestrates
- Docker Compose → Nginx: orchestrates
- Docker Compose → MySQL: orchestrates
- Postfix → Rspamd: filters mail through
- Rspamd → ClamAV: scans with
- Rspamd → Dovecot: delivers filtered mail to
- Postfix → TLS policy: uses
- Dovecot → MySQL: uses metadata
- SOGo → Dovecot: accesses mailboxes via
- SOGo → MySQL: uses
- Nginx → PHP administration: proxies to
- PHP administration → JSON API & OAuth: exposes
- PHP administration → MySQL: reads and writes
- PHP administration → Redis: uses
- PHP administration → Docker API: controls containers through
- Postfix → Unbound: resolves through
- ACME → Nginx: supplies certificates to
- Netfilter → Postfix: enforces network policy for
- Watchdog → Docker Compose: monitors services
- Backup service → MySQL: backs up
- Runtime hooks → Docker Compose: extends service runtime