01it/postfix repository overview

⁠Postfix Docker Image

Lightweight Postfix mail relay with built-in DKIM signing, TLS support, and flexible delivery modes.

⁠Features

• Direct delivery — send mail directly to recipient MX servers (default)
• Relay mode — forward mail through an external SMTP provider (AWS SES, Gmail, etc.)
• DKIM signing — embedded OpenDKIM with automatic key generation
• TLS — auto-generated self-signed certs or Let's Encrypt
• Configurable — all settings via environment variables
• Minimal — multi-stage Debian Trixie build
• Multi-arch — linux/amd64 and linux/arm64

⁠Quick Start

docker run -d --name postfix \
  -e DOMAIN=example.com \
  -e MAILNAME=mail.example.com \
  -p 25:25 -p 587:587 \
  -v dkim_keys:/etc/ssl/dkim \
  01it/postfix:latest

On first startup, the container will:

1. Generate a DKIM key pair and print the DNS TXT record to stdout
2. Generate self-signed TLS certificates
3. Start OpenDKIM and Postfix

Check logs for the DKIM public key:

docker logs postfix 2>&1 | grep -A2 "DKIM PUBLIC KEY"

⁠Operation Modes

⁠Direct Delivery (default)

Mail is delivered directly to recipient MX servers over port 25. This is the default when RELAY_HOST is not set.

Requirements:

• Outbound port 25 must be open (blocked by most cloud providers by default)
• Proper DNS records configured (see DNS Records⁠)

⁠Relay Mode

Mail is forwarded through an external SMTP provider. Activated by setting RELAY_HOST.

environment:
  - RELAY_HOST=[smtp.example.com]:587
  - SMTP_USERNAME=your-username
  - SMTP_PASSWORD=your-password

⁠Authenticated Submission

By default, only clients inside MY_NETWORKS may send mail. To let external clients submit over port 587, provision SASL accounts with SMTP_AUTH_USERS:

environment:
  - SMTP_AUTH_USERS=alice:s3cret,bob:hunter2
ports:
  - "587:587"

Clients authenticate over STARTTLS with the bare username (e.g. alice) and password. Accounts are re-provisioned from the environment on every start, so update the variable and recreate the container to change credentials.

⁠Configuration

⁠Core Settings

⁠DKIM Settings

⁠Relay Settings

⁠TLS Settings

⁠Dynamic Postfix Configuration

Any Postfix directive can be set via POSTFIX_ prefix:

environment:
  - POSTFIX_message_size_limit=52428800
  - POSTFIX_smtp_helo_name=mail.example.com

⁠DNS Records

For reliable mail delivery, configure these DNS records for your domain:

⁠PTR (Reverse DNS)

Your server's IP must have a PTR record matching MAILNAME. Set this at your hosting provider.

203.0.113.1 → mail.example.com

⁠SPF

Authorizes your server to send mail for your domain.

example.com.  IN  TXT  "v=spf1 mx ip4:203.0.113.1 -all"

⁠DKIM

The container prints the DKIM public key on first startup. Add it as a TXT record:

mail._domainkey.example.com.  IN  TXT  "v=DKIM1; k=rsa; p=<PUBLIC_KEY>"

Replace mail with your DKIM_SELECTOR if different.

⁠DMARC

Controls how receivers handle authentication failures.

_dmarc.example.com.  IN  TXT  "v=DMARC1; p=quarantine; rua=mailto:[email protected]"

⁠Let's Encrypt

For production use, real TLS certificates improve deliverability. Set LETSENCRYPT_EMAIL to enable:

environment:
  - [email protected]
  - DOMAIN=example.com
ports:
  - "80:80"    # Required for HTTP-01 challenge
  - "25:25"
  - "587:587"
volumes:
  - letsencrypt:/etc/letsencrypt

Certificates are issued with acme.sh⁠ (HTTP-01, standalone), so port 80 must be accessible from the internet during issuance. Mount the letsencrypt volume to persist the acme.sh account and certificates across restarts. If issuance fails, the container falls back to self-signed certificates.

⁠Volumes

⁠Ports

⁠Cloud Provider Notes

Most cloud providers block outbound port 25 by default:

• AWS: Request removal of port 25 restriction via support ticket
• GCP: Blocked; use a relay or third-party SMTP service
• Azure: Blocked on Basic/Standard tiers; use SendGrid or relay

If port 25 is blocked, use relay mode with an external SMTP provider.

⁠Security

• TLS 1.2+ enforced (SSLv2, SSLv3, TLSv1, TLSv1.1 disabled)
• High-strength ciphers only
• DKIM signing for outbound mail
• SASL-authenticated submission (opt-in via SMTP_AUTH_USERS); otherwise submission is restricted to MY_NETWORKS
• Proper sender/recipient restrictions
• Minimal base image

⁠Logs

All logs go to stdout:

docker logs -f postfix

⁠Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

⁠License

This project is licensed under the MIT License - see the LICENSE file for details.