cisagov/postfix repository overview

⁠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.2.1

⁠Running with Docker Compose

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

   ---
   name: postfix-docker
   
   services:
     postfix:
       build:
         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 compose.yml file:

   ---
   name: postfix-docker
   
   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:
         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.2.1
   

   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.2.1).

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 \
  --tag cisagov/postfix:0.2.1 \
  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 \
     --output type=docker \
     --tag cisagov/postfix:0.2.1 .
   

   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.