docs: document the Docker and compose workflow in the runbook

[AlaskanTuna]

Follow-up to #18, found by auditing the public docs against what actually shipped today.

The gap

grep -ci docker README.md RUNBOOK.md returned 0 for both. #18 landed a multi-stage Dockerfile, a .dockerignore, and a docker-compose.yml this morning, and neither file mentioned any of it. For contrast, #9's Render fallback was documented in the same sweep — 34 mentions in RUNBOOK.md.

Since docs/ is git-excluded, README.md and RUNBOOK.md are the entire public documentation surface. A contributor cloning the repo would find a Dockerfile with no instructions anywhere.

Added

RUNBOOK.md §2.1 "Run locally with Docker (optional)" — placed under Clone and install because compose is primarily a local-dev path, so no section renumbering and no TOC churn. Covers the three-command quickstart, what compose does (prisma migrate deploy before start, mirroring the Procfile release phase), teardown, and a validation checkpoint matching the file's existing style.

It also records the three things that actually cost time when this was built and verified:

• Postgres publishes on host 55432, not 5432 — both 5432 and 5433 were already bound on the dev machine.
• NODE_ENV: production is pinned under environment: deliberately, because environment beats env_file and the repo .env ships NODE_ENV empty. Without it the API answers but the SPA 404s, since the express.static branch in app.ts never runs.
• A port-bind failure can leave the backend unable to reach Postgres (P1001) on retry; docker compose down -v clears it.

README.md — one row in the commands table pointing at the new section.

Verified

Every RUNBOOK.md TOC anchor still resolves · all 11 pnpm commands in the README's table exist in package.json · Prettier clean.

https://claude.ai/code/session_01URDpaxhXyPLWnUQtvowNyM

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 76b4a0a0-b0a8-4360-bf79-b4aa3cdf96f1

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}