docker-postfixrelay

Runs Postfix (as a relay) in Docker

• Source code: GitHub
• Docker container: Docker Hub
• Image base: Alpine Linux
• Init system: dumb-init
• Application: Postfix
• Architecture: linux/amd64,linux/arm64,linux/arm/v7

Explanation

• This runs Postfix (as a relay) in Docker.
• Most home ISPs block port 25, so outbound emails must be relayed through an external SMTP server (e.g., Gmail).
• This container acts as a single collections point for devices needing to send email.
• ⚠️ Postfix acts as an open relay. As such, this is not meant to be run on the internet, only on a trusted internal network! ⚠️

        Internal (LAN) network                                        Public internet

------------------
|                |
| Device sending |                            |   |
| email alert    | -------------              |   |
|                |             |              |   |
------------------             |              |   |
                               |              | F |
------------------             v              | i |
|                |       ------------------   | r |    -----------------------------       -------------------
| Device sending |       |                |   | e |    |                           |       |                 |
| email alert    | ----> | This container | --| w |--> | SMTP server (e.g., Gmail) | ----> | Recipient email |
|                |       |                |   | a |    |                           |       |                 |
------------------       ------------------   | l |    -----------------------------       -------------------
                               ^              | l |
------------------             |              |   |
|                |             |              |   |
| Device sending |             |              |   |
| email alert    | -------------              |   |
|                |
------------------

Requirements

• You must already have an account on an external SMTP server (e.g., Gmail, AWS SES, etc...).
• Your external SMTP server must be using encryption (i.e., plaintext is not allowed)

Docker image information

Docker image tags

• latest: Latest version
• X.X.X: Semantic version (use if you want to stick on a specific version)

Environment variables

Variable	Required?	Definition	Example	Comments
TZ	Yes	Timezone	America/New_York	https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
RELAY_HOST	Yes	Public SMTP server to use	smtp.gmail.com
RELAY_PORT	Yes	Public SMTP port to use	587
RELAY_USER	No	Address to login to $RELAY_HOST	SMTP username
RELAY_PASS	No	Password to login to $RELAY_HOST	SMTP password	If using Gmail 2FA, you will need to setup an app password
TEST_EMAIL	No	Address to receive test email	[email protected]	If not set, test email will not be sent
MYORIGIN	No	Domain of the "from" address	domain.com	Needed for things like AWS SES where the domain must be set
FROMADDRESS	No	Changes the "from" address	[email protected]	Needed for some SMTP services where the FROM address needs to be set, fixes issue 19
MYNETWORKS	No (default: 0.0.0.0/0)	Networks that Postfix will forward mail for	1.2.3.4/24, 5.6.7.8/24	Single or multiple trusted networks separated with a comma
MSG_SIZE	No (default: 10240000)	Postfix message_size_limit in bytes	30720000

Ports

Port on host	Port in container	Comments
Choose at your discretion	25	Postfix SMTP server

Volumes

Volume on host	Volume in container	Comments
Choose at your discretion	/var/spool/postfix	Used to store Postfix's mail spool

Example usage

Below is an example docker-compose.yml file.

version: '3'
services:
  postfixrelay:
    container_name: docker-postfixrelay
    restart: unless-stopped
    environment:
      - TZ=America/New_York
      - RELAY_HOST=smtp.gmail.com
      - RELAY_PORT=587
      - [email protected]
      - RELAY_PASS=your_password_here
      - [email protected]
      - MYORIGIN=domain.com
      - [email protected]
      - MYNETWORKS=1.2.3.4/24
      - MSG_SIZE=30720000
    networks:
      - postfixrelay
    ports:
      - '25:25'
    volumes:
      - 'postfixrelay_data:/var/spool/postfix'
    image: loganmarchione/docker-postfixrelay:latest

networks:
  postfixrelay:

volumes:
  postfixrelay_data:
    driver: local

Below is an example of running locally (used to edit/test/debug).

# Build the Dockerfile
docker compose -f docker-compose-dev.yml up -d

# View logs
docker compose -f docker-compose-dev.yml logs -f

# Destroy when done
docker compose -f docker-compose-dev.yml down

TODO

• Add a healthcheck
• Add TLS support for SMTPD and listen on 587