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

```bash
docker network create postfix-test-net
```

## 2. Start PostgreSQL with the relay_domain schema

```bash
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:

```bash
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:
```bash
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.

```bash
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

```bash
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:
```bash
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`:

```bash
# 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:
```bash
ssh -L 8025:localhost:8025 user@your-host
```
Then open `http://localhost:8025` in a browser.

**HTTP API** (no tunnel needed):
```bash
curl -s http://localhost:8025/api/v2/messages | jq '.items[].Content.Headers.Subject'
```

## 7. Cleanup

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