postfix-docker 📮🐳

Docker Image

Creates a Docker container with an installation of the postfix⁠ MTA. Additionally it has an IMAP server (dovecot⁠) for accessing the archives of sent email. All email is BCC'd to the mailarchive account.

Running

Running with Docker

To run the cisagov/postfix image via Docker:

docker run cisagov/postfix:0.0.4

Running with Docker Compose

1. Create a docker-compose.yml file similar to the one below to use Docker Compose⁠ or use the sample docker-compose.yml provided with this repository.

   ---
   version: "3.7"
   
   services:
     postfix:
       build:
         # VERSION must be specified on the command line:
         # e.g., --build-arg VERSION=0.0.4
         context: .
         dockerfile: Dockerfile
       image: cisagov/postfix
       init: true
       restart: always
       environment:
         - PRIMARY_DOMAIN=example.com
         - RELAY_IP=172.16.202.1/32
       networks:
         front:
           ipv4_address: 172.16.202.2
       ports:
         - target: "25"
           published: "1025"
           protocol: tcp
           mode: host
         - target: "587"
           published: "1587"
           protocol: tcp
           mode: host
         - target: "993"
           published: "1993"
           protocol: tcp
           mode: host
   
   networks:
     front:
       driver: bridge
       ipam:
         driver: default
         config:
           - subnet: 172.16.202.0/24
   

   Copy

2. Start the container and detach:

   docker compose up --detach
   

   Copy

Using secrets with your container

This container also supports passing sensitive values via Docker secrets⁠. Passing sensitive values like your credentials can be more secure using secrets than using environment variables. See the secrets section below for a table of all supported secret files.

1. To use secrets, populate the following files in the src/secrets directory:

• fullchain.pem
• privkey.pem
• users.txt

1. Then add the secrets to your docker-compose.yml file:

   ---
   version: "3.7"
   
   secrets:
     fullchain_pem:
       file: ./src/secrets/fullchain.pem
     privkey_pem:
       file: ./src/secrets/privkey.pem
     users_txt:
       file: ./src/secrets/users.txt
   
   services:
     postfix:
       build:
         # VERSION must be specified on the command line:
         # e.g., --build-arg VERSION=0.0.4
         context: .
         dockerfile: Dockerfile
       image: cisagov/postfix
       init: true
       restart: always
       environment:
         - PRIMARY_DOMAIN=example.com
         - RELAY_IP=172.16.202.1/32
       networks:
         front:
           ipv4_address: 172.16.202.2
       ports:
         - target: "25"
           published: "1025"
           protocol: tcp
           mode: host
         - target: "587"
           published: "1587"
           protocol: tcp
           mode: host
         - target: "993"
           published: "1993"
           protocol: tcp
           mode: host
       secrets:
         - source: fullchain_pem
           target: fullchain.pem
         - source: privkey_pem
           target: privkey.pem
         - source: users_txt
           target: users.txt
   
   networks:
     front:
       driver: bridge
       ipam:
         driver: default
         config:
           - subnet: 172.16.202.0/24
   

   Copy

Updating your container

Docker Compose

1. Pull the new image from Docker Hub:

   docker compose pull
   

   Copy

2. Recreate the running container by following the previous instructions:

   docker compose up --detach
   

   Copy

Docker

1. Stop the running container:

   docker stop <container_id>
   

   Copy

2. Pull the new image:

   docker pull cisagov/postfix:0.0.4
   

   Copy

3. Recreate and run the container by following the previous instructions.

Image tags

The images of this container are tagged with semantic versions⁠ of the underlying Postfix project that they containerize. It is recommended that most users use a version tag (e.g. :0.0.4).

See the tags tab on Docker Hub for a list of all the supported tags.

Volumes

Ports

The following ports are exposed by this container:

The sample Docker composition publishes the exposed ports at 1025, 1587, and 1993, respectively.

Environment variables

Required

Optional

Secrets

Building from source

Build the image locally using this git repository as the build context⁠:

docker build \
  --build-arg VERSION=0.0.4 \
  --tag cisagov/postfix:0.0.4 \
  https://github.com/cisagov/postfix-docker.git#develop

Cross-platform builds

To create images that are compatible with other platforms, you can use the buildx⁠ feature of Docker:

1. Copy the project to your machine using the Code button above or the command line:

   git clone https://github.com/cisagov/postfix-docker.git
   cd postfix-docker
   

   Copy

2. Create the Dockerfile-x file with buildx platform support:

   ./buildx-dockerfile.sh
   

   Copy

3. Build the image using buildx:

   docker buildx build \
     --file Dockerfile-x \
     --platform linux/amd64 \
     --build-arg VERSION=0.0.4 \
     --output type=docker \
     --tag cisagov/postfix:0.0.4 .
   

   Copy

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

License

This project is in the worldwide public domain.

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication⁠.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.