docs(postfix-pgsql): add test setup guide and test plan

images/postfix-pgsql/tests/setup.md

@@ -0,0 +1,142 @@
+# 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
+```