docker-postfix

Simple postfix relay host ("postfix null client") for your Docker containers. Based on Debian (default), Ubuntu and Alpine Linux. Feel free to pick your favourite distro.

Table of contents

• docker-postfix
  • Table of contents
  • Description
  • TL;DR
  • Updates
    • v4.0.0
    • v3.0.0
  • Architectures
  • Configuration options
    • General options
      • Inbound debugging
      • ALLOWED_SENDER_DOMAINS and ALLOW_EMPTY_SENDER_DOMAINS
      • Log format
    • Postfix-specific options
      • RELAYHOST, RELAYHOST_USERNAME and RELAYHOST_PASSWORD
      • POSTFIX_smtp_tls_security_level
      • XOAUTH2_CLIENT_ID, XOAUTH2_SECRET, XOAUTH2_INITIAL_ACCESS_TOKEN, XOAUTH2_INITIAL_REFRESH_TOKEN and XOAUTH2_TOKEN_ENDPOINT
        • OAuth2 Client Credentials (GMail)
        • Obtain Initial Access Token (GMail)
        • Debug XOAuth2 issues
      • MASQUERADED_DOMAINS
      • SMTP_HEADER_CHECKS
      • POSTFIX_myhostname
      • POSTFIX_mynetworks
      • POSTFIX_message_size_limit
      • Overriding specific postfix settings
      • SKIP_ROOT_SPOOL_CHOWN
      • ANONYMIZE_EMAILS
        • The default (smart) filter
        • The paranoid filter
        • The hash filter
        • The noop filter
        • Writing your own filters
    • DKIM / DomainKeys
      • Supplying your own DKIM keys
      • Auto-generating the DKIM selectors through the image
      • Changing the DKIM selector
      • Overriding specific OpenDKIM settings
      • Verifying your DKIM setup
    • Docker Secrets / Kubernetes secrets
  • Helm chart
    • Metrics
  • Extending the image
    • Using custom init scripts
  • Security
    • UIDs/GIDs numbers
  • Quick how-tos
    • Relaying messages through your Gmail account
    • Relaying messages through Google Apps account
    • Relaying messages through Amazon's SES
    • Sending messages directly
      • Careful
  • Similar projects
  • License check

Description

This image allows you to run POSTFIX internally inside your docker cloud/swarm installation to centralise outgoing email sending. The embedded postfix enables you to either send messages directly or relay them to your company's main server.

This is a server side POSTFIX image, geared towards emails that need to be sent from your applications. That's why this postfix configuration does not support username / password login or similar client-side security features.

IF YOU WANT TO SET UP AND MANAGE A POSTFIX INSTALLATION FOR END USERS, THIS IMAGE IS NOT FOR YOU. If you need it to manage your application's outgoing queue, read on.

TL;DR

To run the container, do the following:

docker run --rm --name postfix -e "ALLOWED_SENDER_DOMAINS=example.com" -p 1587:587 boky/postfix

or

helm repo add bokysan https://bokysan.github.io/docker-postfix/
helm upgrade --install --set persistence.enabled=false --set config.general.ALLOW_EMPTY_SENDER_DOMAINS=yes mail bokysan/mail

You can also find this image at ArtifactHub.

You can now send emails by using localhost:1587 (on Docker) as your SMTP server address. Note that if you haven't configured your domain to allow sending from this IP/server/nameblock, your emails will most likely be regarded as spam.

All standard caveats of configuring the SMTP server apply:

• MAKE SURE YOUR OUTGOING PORT 25 IS NOT BLOCKED.
  • Most ISPs block outgoing connections to port 25 and several companies (e.g. NoIP, Dynu) offer workarounds.
  • Hosting centers also tend to block port 25, which can be unblocked per request, see below for AWS hosting.
• You'll most likely need to at least set up SPF records (see also openspf) and/or DKIM.
• If using DKIM (below), make sure to add DKIM keys to your domain's DNS entries.
• You'll most likely need to set up PTR records as well to prevent your mails going to spam.

If you don't know what any of the above means, get some help. Google is your friend. It's also worth noting that it's pretty difficult to host a SMTP server on a dynamic IP address.

Please note that the image uses the submission (587) port by default. Port 25 is not exposed on purpose, as it's regularly blocked by ISPs, already occupied by other services, and in general should only be used for server-to-server communication.

Updates

v4.0.0

Several potentially "surprising" changes went into this issue and hence warrant a version upgrade:

• Default image is now based on Debian. A lot of packages needed for latest builds are missing in certain Alpine architectures. Debian allows us to have a greater cross-platform availability.
• Helm charts are now built with v and without v prefix. As seen in PR #141 some tools rely on version not having the prefix. I've seen both in the wild, so the image now includes both. This should work and should hopefully provide most compatibility.
• master branch now builds images called edge. latest images are built from the last tag. We've had several issues with people using the latest tag and reporting problems. You can now rely on latest being the latest stable release.
• Image now builds its own version of postfix-exporter and relies on this third-party project. Checkout is from master branch, based on specific SHA commit id. The same hash is used for master and tags.
• Architecture galore! With the addition of debian images, we now support support more architectures than ever. The list includes: linux/386, linux/amd64, linux/arm/v5, linux/arm/v6, linux/arm/v7, linux/arm64, linux/arm64/v8, linux/mips64le, linux/ppc64le and linux/s390x.
• smtpd_tls_security_level is now set to may. If you encounter issues, try setting it to none explicitly (see #160).

v3.0.0

There's a potentially breaking change introduced now in v3.0.0: Oracle has changed the license of BerkleyDB to AGPL-3.0, making it unsuitable to link to packages with GPL-incompatible licenses. As a result Alpine (on which this image is based) has deprecated BerkleyDB throughout the image:

Support for Postfix hash and btree databases has been removed. lmdb is the recommended replacement. Before upgrading, all tables in /etc/postfix/main.cf using hash and btree must be changed to a supported alternative. See the Postfix lookup table documentation for more information.

While this should not affect most of the users (/etc/postfix/main.cf is managed by this image), there might be use cases where people have their own configuration which relies on hash and btree databases. To avoid braking live systems, the version of this image has been updated to v3.0.0.

Architectures

Available for all your favourite architectures. Run in your server cluster. Run it on your Raspberry Pi 4. Run it on your ancient Pentium or an old Beaglebone. The following architectures are supported: linux/386, linux/amd64, linux/arm/v6, linux/arm/v7, linux/arm64 and linux/ppc64le.

Configuration options

General options

• TZ = The timezone for the image, e.g. Europe/Amsterdam
• FORCE_COLOR = Set to 1 to force color output (otherwise auto-detected)
• INBOUND_DEBUGGING = Set to 1 to enable detailed debugging in the logs
• ALLOWED_SENDER_DOMAINS = domains which are allowed to send email via this server
• ALLOW_EMPTY_SENDER_DOMAINS = if value is set (i.e: true), ALLOWED_SENDER_DOMAINS can be unset
• LOG_FORMAT = Set your log format (JSON or plain)

Inbound debugging

Enable additional debugging for any connection coming from POSTFIX_mynetworks. Set to a non-empty string (usually 1 or yes) to enable debugging.

ALLOWED_SENDER_DOMAINS and ALLOW_EMPTY_SENDER_DOMAINS

Due to in-built spam protection in Postfix you will need to specify sender domains -- the domains you are using to send your emails from, otherwise Postfix will refuse to start.

Example:

docker run --rm --name postfix -e "ALLOWED_SENDER_DOMAINS=example.com example.org" -p 1587:587 boky/postfix

If you want to set the restrictions on the recipient and not on the sender (anyone can send mails but just to a single domain for instance), set ALLOW_EMPTY_SENDER_DOMAINS to a non-empty value (e.g. true) and ALLOWED_SENDER_DOMAINS to an empty string. Then extend this image through custom scripts to configure Postfix further.

Log format

The image will by default output logs in human-readable (plain) format. If you are deploying the image to Kubernetes, it might be worth changing the output format to json as it's more easily parsable by tools such as Prometheus.

To change the log format, set the (unsurprisingly named) variable LOG_FORMAT=json.

Postfix-specific options

• RELAYHOST = Host that relays your messages
• SASL_RELAYHOST = (optional) Relay Host referenced in the sasl_passwd file. Defaults to the value of RELAYHOST
• RELAYHOST_USERNAME = An (optional) username for the relay server
• RELAYHOST_PASSWORD = An (optional) login password for the relay server
• RELAYHOST_PASSWORD_FILE = An (optional) file containing the login password for the relay server. Mutually exclusive with the previous option.
• POSTFIX_smtp_tls_security_level = Relay host TLS connection level
• XOAUTH2_CLIENT_ID = OAuth2 client id used when configured as a relayhost.
• XOAUTH2_SECRET = OAuth2 secret used when configured as a relayhost.
• XOAUTH2_INITIAL_ACCESS_TOKEN = Initial OAuth2 access token.
• XOAUTH2_INITIAL_REFRESH_TOKEN = Initial OAuth2 refresh token.
• XOAUTH2_TOKEN_ENDPOINT = Token endpoint provided four your XOAUTH App , GMail use : https://accounts.google.com/o/oauth2/token
• SMTPD_SASL_USERS = Users allow to send mail (ex: user1:pass1,user2:pass2,...). Warning: Users need to be specified with a domain, as explained on ticket [#192]. This image will automatically add a domain if one is not provided and will issue a notice when that happens.
• MASQUERADED_DOMAINS = domains where you want to masquerade internal hosts
• SMTP_HEADER_CHECKS= Set to 1 to enable header checks of to a location of the file for header checks
• POSTFIX_myhostname = Set the name of this postfix server
• POSTFIX_mynetworks = Allow sending mails only from specific networks ( default 127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16 )
• POSTFIX_message_size_limit = The maximum size of the message, in bytes, by default it's unlimited
• POSTFIX_<any_postfix_setting> = provide any additional postfix setting

RELAYHOST, RELAYHOST_USERNAME and RELAYHOST_PASSWORD

Postfix will try to deliver emails directly to the target server. If you are behind a firewall, or inside a corporation you will most likely have a dedicated outgoing mail server. By setting this option, you will instruct postfix to relay (hence the name) all incoming emails to the target server for actual delivery.

Example:

docker run --rm --name postfix -e RELAYHOST=192.168.115.215 -p 1587:587 boky/postfix

You may optionally specifiy a relay port, e.g.:

docker run --rm --name postfix -e RELAYHOST=192.168.115.215:587 -p 1587:587 boky/postfix

Or an IPv6 address, e.g.:

docker run --rm --name postfix -e