Skip to content
optimodePublic

About

A Postfix docker image

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

 

History

11 Commits

Folders and files

Repository files navigation

docker-postfix

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.

Versions

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.2 image 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-alpine tag (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) and latest-alpine. For reproducible deployments use the exact version tag.

Usage

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-alpine

See docker-compose.yml for a commented compose sample.

Configuration notes

  • Configuration is expected at /etc/postfix (main.cf, master.cf, lookup tables). Postfix only loads dynamic map modules (lmdb, mysql, pcre, sqlite) from root-owned dynamicmaps.cf files — 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 via maillog_file = /data/log/postfix.log with maillog_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 tzdata package is included, so both the TZ environment variable (e.g. TZ=Europe/Budapest) and a mounted /etc/localtime are honoured; log timestamps are written in local time. If you use both, make sure they point to the same zone (TZ wins).
  • TLS: mount your certificates and point smtpd_tls_cert_file / smtpd_tls_key_file to 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 saslauthd with the sasldb backend; Dovecot SASL authentication is supported through smtpd_sasl_type = dovecot with smtpd_sasl_path = inet:... or a mounted auth socket.
  • Processes: runit (runsvdir) is PID 1 and supervises the services under rootfs/etc/service/ (see below).

Services

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=0

A 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/saslauthd

Building

make 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 variables

The build is reproducible by design:

  • ALPINE_VERSION selects 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.

Image metadata

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.tool

License

MIT — see LICENSE.

About

A Postfix docker image

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Packages

Contributors

Languages