Alpine-based Postfix MTA Docker image with LMDB/MySQL/SQLite/PCRE lookup table support and Cyrus SASL.
The container is managed by runit (PID 1: runsvdir) and supervises four
services: Postfix (as master -s), saslauthd (Cyrus SASL), OpenDKIM
(when configured) and rsyslog. Configuration is mounted at /etc/postfix,
the mail queue lives in /var/spool/postfix and logs go to /data/log
where rsyslog writes and rotates them.
This project uses Semantic Versioning for
its git tags (e.g. v1.0.0); every release is tagged in git. The table shows
exactly which Alpine and Postfix versions each Docker image has and when it was
built.
| Git tag | Alpine | Postfix | Build date | Docker image |
|---|---|---|---|---|
| — (not tagged) | 3.22.0 | 3.10.2 | 2025-06-30 | ghcr.io/optimode/postfix:3.10.2-alpine |
v1.0.0 |
3.24.2 | 3.11.7 | 2026-10-29 | ghcr.io/optimode/postfix:3.11.7-alpine |
v1.1.0 |
3.24.2 | 3.11.7 | 2026-11-07 | ghcr.io/optimode/postfix:3.11.7-alpine |
v1.2.0 |
3.24.2 | 3.11.7 | 2026-11-07 | ghcr.io/optimode/postfix:3.11.7-alpine |
v1.2.1 |
3.24.2 | 3.11.7 | 2026-11-07 | ghcr.io/optimode/postfix:3.11.7-alpine |
Notes:
- The
3.10.2image predates the git tagging scheme of this repository and is listed for reference only. - The Docker image tag reflects the Postfix version, not the git tag:
every release rebuilds the same
3.11.7-alpinetag (v1.1.0 with the supervisor-managed layout, v1.2.0 with runit and selectable services, v1.2.1 with the svlogd stderr fix, see CHANGELOG.md). - Besides the exact version tag (e.g.
3.11.7-alpine) each build produces two moving tags:3.11-alpine(latest patch level of Postfix 3.11) andlatest-alpine. For reproducible deployments use the exact version tag.
docker run -d --name postfix \
-e TZ=Europe/Budapest \
-p 25:25 -p 465:465 -p 587:587 \
-v ./etc:/etc/postfix \
-v ./certs:/etc/ssl/postfix:ro \
-v ./log:/data/log \
-v postfix-spool:/var/spool/postfix \
ghcr.io/optimode/postfix:3.11.7-alpineSee docker-compose.yml for a commented compose sample.
- Configuration is expected at
/etc/postfix(main.cf,master.cf, lookup tables). Postfix only loads dynamic map modules (lmdb, mysql, pcre, sqlite) from root-owneddynamicmaps.cffiles — make sure the mounted files are owned by root (chown -R root:root ./etc). - Logging: rsyslog writes the logs of all container processes into the
mounted log directory:
/data/log/mail.log(postfix, opendkim),/data/log/auth.log(saslauthd) and/data/log/syslog(everything else). Each stream is rotated automatically at 50 MiB and 7 gzip-compressed archives are kept. Alternatively Postfix can log to its own file viamaillog_file = /data/log/postfix.logwithmaillog_file_prefixes = /data/log— but do not combine the two, or every Postfix message is logged twice. Each service additionally keeps its own stderr in/data/log/<service>/via runit's svlogd (built-in size-based rotation). - Timezone: the
tzdatapackage is included, so both theTZenvironment variable (e.g.TZ=Europe/Budapest) and a mounted/etc/localtimeare honoured; log timestamps are written in local time. If you use both, make sure they point to the same zone (TZwins). - TLS: mount your certificates and point
smtpd_tls_cert_file/smtpd_tls_key_fileto the mounted paths. All three submission ports are exposed: 25 (SMTP), 465 (SMTPS wrappermode), 587 (submission). Port 8891 is exposed for an OpenDKIM milter. - SASL: the image contains Cyrus SASL and runs
saslauthdwith thesasldbbackend; Dovecot SASL authentication is supported throughsmtpd_sasl_type = dovecotwithsmtpd_sasl_path = inet:...or a mounted auth socket. - Processes: runit (
runsvdir) is PID 1 and supervises the services underrootfs/etc/service/(see below).
runit supervises one directory per service under
rootfs/etc/service/. Which services start can be controlled at container
start with environment variables:
| Service | Default | Control |
|---|---|---|
rsyslog, postfix |
always on | — |
saslauthd |
on | ENABLE_SASLAUTHD=0 |
opendkim |
auto: starts when /etc/opendkim/opendkim.conf is present and valid (opendkim -n) |
ENABLE_OPENDKIM=0 (off), ENABLE_OPENDKIM=1 (force on) |
Typical profiles (via environment in docker-compose.yml):
- Standalone smtp-only MTA: no variables needed — opendkim starts as
soon as a valid config and keys are mounted at
/etc/opendkim. - Bigger ecosystem (dovecot provides SASL, rspamd signs DKIM) or OpenDKIM in its own container:
services:
postfix:
environment:
- TZ=Europe/Budapest
# dovecot provides SASL, rspamd signs DKIM:
- ENABLE_SASLAUTHD=0
# rspamd signs DKIM, or opendkim runs in its own container:
- ENABLE_OPENDKIM=0A disabled service is not removed: it starts in the down state and stays
supervised. Services can also be controlled at runtime with sv:
docker exec postfix sv status /etc/service/*
docker exec postfix sv up /etc/service/opendkim
docker exec postfix sv down /etc/service/saslauthdmake build # build with the default versions
make build push # build and push all tags
make build POSTFIX_VERSION=3.11.8 ALPINE_VERSION=3.24.3
make help # list targets and variablesThe build is reproducible by design:
ALPINE_VERSIONselects the exact Alpine base image (default:3.24.2).POSTFIX_VERSION(default:3.11.7) is pinned in the Dockerfile for all four postfix packages (postfix,postfix-mysql,postfix-sqlite,postfix-pcre). The~=pin accepts Alpine package rebuilds of the same upstream version (3.11.7-rX) but rejects any other version.- A build-time check fails the build loudly if the planned Postfix version was not installed.
The image carries OCI labels with the build metadata:
| Label | Content |
|---|---|
org.opencontainers.image.version |
Postfix version (e.g. 3.11.7) |
org.opencontainers.image.created |
build date (RFC 3339) |
org.opencontainers.image.revision |
git revision the image was built from |
org.opencontainers.image.base.name |
base image (e.g. alpine:3.24.2) |
org.opencontainers.image.url, .source |
project and source repository |
org.opencontainers.image.authors, .vendor, .licenses |
authors, vendor, license |
Inspect them with:
docker inspect ghcr.io/optimode/postfix:3.11.7-alpine \
--format '{{json .Config.Labels}}' | python3 -m json.toolMIT — see LICENSE.