cisagov/postfix-docker

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

1. Start the container and detach:

    docker compose up --detach

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

Updating your container ##

Docker Compose ###

1. Pull the new image from Docker Hub:

    docker compose pull

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

    docker compose up --detach

Docker ###

1. Stop the running container:

    docker stop <container_id>

1. Pull the new image:

    docker pull cisagov/postfix:0.2.1

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

| Image:tag | Description | | --------- | ----------- | | cisagov/postfix:0.2.1 | An exact release version. | | cisagov/postfix:0.2 | The most recent release matching the major and minor version numbers. | | cisagov/postfix:0 | The most recent release matching the major version number. | | cisagov/postfix:edge | The most recent image built from a merge into the develop branch of this repository. | | cisagov/postfix:nightly | A nightly build of the develop branch of this repository. | | cisagov/postfix:latest | The most recent release image pushed to a container registry. Pulling an image using the :latest tag should be avoided. |

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

Volumes ##

| Mount point | Purpose | | ----------- | ------- | | /var/log | System logs | | /var/spool/postfix | Mail queues |

Ports ##

The following ports are exposed by this container:

| Port | Purpose | | ---- | ------- | | 25 | SMTP relay | | 587 | Mail submission | | 993 | IMAPS |

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

Environment variables ##

Required ###

| Name | Purpose | | ---- | ------- | | PRIMARY_DOMAIN | The primary domain of the mail server. |

Optional ###

| Name | Purpose | Default | | ---- | ------- | ------- | | RELAY_IP | An IP address that is allowed to relay mail without authentication. | null |

Secrets ##

| Filename | Purpose | | -------- | ------- | | fullchain.pem | Public key for the Postfix server. | | privkey.pem | Private key for the Postfix server. | | users.txt | Mail account credentials to create at startup. |

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

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

    ./buildx-dockerfile.sh

1. Build the image using buildx:

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

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.