Local Test Environment Setup

Step-by-step instructions for standing up a self-contained test environment for the postfix-pgsql image on any Linux host with Docker installed. No cloud access is required.

Architecture

External SMTP client (e.g. swaks / telnet)
        |
        | :25
        v
  [ postfix-pgsql ]  ──pgsql lookup──>  [ postgres ]
        |
        | :2525 (SMTP_RELAY_PORT)
        v
    [ mailhog ]   <── captured mail browsable at :8025

MailHog acts as a stand-in for the downstream SMTP consumer and captures every message delivered to it, making it easy to verify end-to-end relay without actually sending real mail.

1. Create a dedicated Docker network

All containers must share the same network so they can resolve each other by container name (required because chroot is disabled in this image — see the README).

docker network create postfix-test-net

2. Start PostgreSQL with the relay_domain schema

docker run -d \
  --name test-postgres \
  --network postfix-test-net \
  -e POSTGRES_USER=relayuser \
  -e POSTGRES_PASSWORD=testpassword \
  -e POSTGRES_DB=relaydb \
  postgres:16-alpine

Wait for Postgres to be ready, then create the relay_domain table and insert a test domain:

docker exec -i test-postgres psql -U relayuser -d relaydb <<'SQL'
CREATE TABLE relay_domain (domain TEXT PRIMARY KEY);
INSERT INTO relay_domain VALUES ('example.com');
SQL

Verify:

docker exec -i test-postgres psql -U relayuser -d relaydb -c "SELECT * FROM relay_domain;"

3. Start MailHog

MailHog listens on port 2525 for SMTP (matching SMTP_RELAY_PORT) and exposes a web UI on port 8025.

docker run -d \
  --name test-mailhog \
  --network postfix-test-net \
  -p 8025:8025 \
  mailhog/mailhog \
  MailHog -smtp-bind-addr 0.0.0.0:2525

4. Start the postfix-pgsql container

docker run -d \
  --name test-postfix \
  --network postfix-test-net \
  -p 25:25 \
  -e MAIL_DOMAIN=example.com \
  -e MYHOSTNAME=mx1.example.com \
  -e POSTGRES_HOST=test-postgres \
  -e POSTGRES_PORT=5432 \
  -e POSTGRES_USER=relayuser \
  -e POSTGRES_PASSWORD=testpassword \
  -e POSTGRES_DB=relaydb \
  -e SMTP_RELAY_HOST=test-mailhog \
  -e SMTP_RELAY_PORT=2525 \
  gitea.arnodo.fr/damien/postfix-pgsql:latest

Confirm it started cleanly:

docker logs test-postfix

Expected: Postfix master process line and no errors.

5. Send a test message

You can use swaks (Swiss Army Knife for SMTP) or plain telnet:

# With swaks (install: apt install swaks / brew install swaks)
swaks --to user@example.com \
      --from sender@external.com \
      --server 127.0.0.1 \
      --port 25

# Or with telnet
telnet 127.0.0.1 25
  EHLO test
  MAIL FROM:<sender@external.com>
  RCPT TO:<user@example.com>
  DATA
  Subject: Test
  .
  QUIT

6. View captured mail in MailHog

Web UI — if testing on a remote host, open an SSH tunnel first:

ssh -L 8025:localhost:8025 user@your-host

Then open http://localhost:8025 in a browser.

HTTP API (no tunnel needed):

curl -s http://localhost:8025/api/v2/messages | jq '.items[].Content.Headers.Subject'

7. Cleanup

docker rm -f test-postfix test-mailhog test-postgres
docker network rm postfix-test-net

3.3 KiB Raw Blame History