ricariel/postfix repository overview

⁠Docker Postfix

A flexible and modern Docker image for a Postfix mail server, based on Debian Trixie.

⁠Features

• Debian Trixie: Built on a modern base image with Postfix 3.10.x.
• Flexible Configuration: Configure any Postfix parameter via POSTFIX_* environment variables — no config files to edit.
• Secure by Default: Enables submission (587) and smtps (465) with TLS and SASL authentication out of the box.
• Database Integration: Includes postfix-ldap and postfix-mysql for user lookups, virtual mailboxes and aliases.
• Extensible: Drop additional scripts into docker-entrypoint.d/ to extend the startup sequence.
• Automated Maintenance: Runs postfix check and postfix upgrade-configuration on every start.
• Container-ready: Logs to stdout, exposes a HEALTHCHECK, handles signals for graceful shutdown.

⁠Quickstart

docker run -d --name postfix \
  -e POSTFIX_myhostname=mail.example.com \
  -e POSTFIX_mydomain=example.com \
  -e POSTFIX_mynetworks="127.0.0.0/8" \
  -p 25:25 \
  -p 587:587 \
  -p 465:465 \
  ricariel/postfix

⁠Startup Sequence

On container start, the entrypoint executes all scripts inside /docker-entrypoint.d/ in lexicographic order via run-parts, then starts Postfix:

Custom scripts added via derived images are sorted into this sequence by their filename prefix.

⁠Configuration

⁠Environment Variables

⁠ENTRYPOINT_QUIET_LOGS

Suppresses the startup log output of the entrypoint script itself. Postfix's own logs (via maillog_file) are unaffected.

-e ENTRYPOINT_QUIET_LOGS=1

⁠POSTFIX_* — Postfix main.cf settings

Every environment variable with the POSTFIX_ prefix is applied to /etc/postfix/main.cf at startup. The prefix is stripped; the remainder is used as the Postfix parameter name (case-sensitive).

Set a value:

-e POSTFIX_myhostname=mail.example.com
-e POSTFIX_mynetworks="127.0.0.0/8 10.0.0.0/8"

Delete / disable a setting (empty value comments it out in main.cf):

-e POSTFIX_relayhost=

⁠Reference: commonly used POSTFIX_* variables

Core identity

Network

Relay

Virtual domains and mailboxes

TLS — inbound (smtpd)

TLS — outbound (smtp)

SASL authentication via Dovecot

Milter integration (Rspamd, ClamAV-milter, etc.)

Rate limiting

Miscellaneous

For the full list of Postfix parameters, see the Postfix documentation⁠.

⁠Ports

⁠Volumes and Mounts

⁠/config/ldap/

Mount a directory containing Postfix LDAP lookup table configuration files (.cf files). They are copied into /etc/postfix/ldap/ at startup by 10-copy.

docker run -d --name postfix \
  -v /path/to/ldap-configs:/config/ldap:ro \
  ...
  ricariel/postfix

Example main.cf references:

virtual_mailbox_maps  = ldap:/etc/postfix/ldap/virtual_mailbox.cf
virtual_alias_maps    = ldap:/etc/postfix/ldap/aliases.cf
smtpd_sender_login_maps = ldap:/etc/postfix/ldap/sender_login.cf

A minimal LDAP lookup file looks like this:

server_host     = ldaps://ldap.example.com:636
bind            = yes
bind_dn         = cn=postfix,ou=services,dc=example,dc=com
bind_pw         = secret
search_base     = ou=users,dc=example,dc=com
query_filter    = (mail=%s)
result_attribute = mail

⁠TLS certificates

Mount your certificate and key files and point Postfix to them via environment variables:

docker run -d --name postfix \
  -v /etc/letsencrypt/live/smtp.example.com:/etc/postfix/certs:ro \
  -e POSTFIX_smtpd_tls_cert_file=/etc/postfix/certs/fullchain.pem \
  -e POSTFIX_smtpd_tls_key_file=/etc/postfix/certs/privkey.pem \
  ...
  ricariel/postfix

⁠Mail spool

Postfix stores its mail queue under /var/spool/postfix/. For persistence across container restarts (e.g. to avoid losing queued messages on restart), mount a volume:

-v postfix-spool:/var/spool/postfix

⁠SQL lookup tables

In addition to LDAP, postfix-mysql is included for MySQL/MariaDB-based setups. See example_sql_map.md⁠ for example database schemas and query configurations covering virtual mailboxes, aliases, forwarding, and catch-all rules.

⁠Extending the Image

⁠Adding custom startup scripts

Any executable file placed in /docker-entrypoint.d/ of a derived image is automatically executed at startup. Use the numeric prefix to control execution order relative to the built-in scripts (10, 20, 25, 30, 99).

FROM ricariel/postfix

# Runs between 25-postconf and 30-maintenance
COPY --chmod=755 28-my-custom-setup.sh /docker-entrypoint.d/

The ONBUILD instruction in this image's Dockerfile automatically copies docker-entrypoint.d/* from the child image's build context, so no explicit COPY is needed if you place the scripts in the same directory.

⁠Overriding the default command

The default CMD is postfix start-fg. You can override it for debugging:

docker run --rm -it ricariel/postfix bash

⁠Docker Compose Example

services:
  postfix:
    image: ricariel/postfix
    restart: unless-stopped
    ports:
      - "25:25"
      - "587:587"
      - "465:465"
    volumes:
      - ./ldap:/config/ldap:ro
      - ./certs:/etc/postfix/certs:ro
      - postfix-spool:/var/spool/postfix
    environment:
      POSTFIX_myhostname: smtp.example.com
      POSTFIX_mydomain: example.com
      POSTFIX_mynetworks: "127.0.0.0/8"
      POSTFIX_virtual_mailbox_domains: "example.com"
      POSTFIX_virtual_transport: "lmtp:dovecot:24"
      POSTFIX_smtpd_tls_cert_file: /etc/postfix/certs/tls.crt
      POSTFIX_smtpd_tls_key_file: /etc/postfix/certs/tls.key
      POSTFIX_smtpd_tls_security_level: may
      POSTFIX_smtpd_sasl_type: dovecot
      POSTFIX_smtpd_sasl_path: "inet:dovecot:8745"
      POSTFIX_smtpd_sasl_auth_enable: "yes"
      POSTFIX_smtpd_milters: "inet:rspamd:11332"
      POSTFIX_non_smtpd_milters: "inet:rspamd:11332"
      POSTFIX_maillog_file: /dev/stdout

volumes:
  postfix-spool:

⁠Postfix Version Notes (3.8 → 3.10)

This image ships Postfix 3.10.x (Debian Trixie). If you are migrating from a Bookworm-based setup (Postfix 3.7.x), be aware of the following behavioral changes introduced across releases 3.8–3.10:

⁠Breaking changes (3.9)

⁠TLS hardening (3.8)

• "Export" and "low" cipher grades are silently promoted to "medium". Weak ciphers (3DES, RC4, SEED, IDEA, RC2, RC5) are no longer negotiated.
• TLS renegotiation is unconditionally disabled.
• postconf now warns if a # comment appears on the same line as a parameter value — move inline comments to their own line.

⁠Improvements (3.10)

• OpenSSL 3.5 post-quantum cryptography support for outbound TLS.
• Queue IDs are included in abnormal connection closure logs (better container log parsing).
• SASL failure logs now include the mechanism name.
• MySQL/PostgreSQL map connections reconnect immediately after a single failure (previously all queries were blocked for 60 seconds).

⁠License

This project is licensed under the MIT License. See the LICENSE⁠ file for details.