Step 1.5: add local Postgres via Docker Compose

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.env.example

@@ -0,0 +1,18 @@
+# Copy to .env and adjust. Values below match docker-compose.yml.
+
+# Postgres: development and test databases (same server, see docker-compose.yml)
+DATABASE_URL=postgres://deadhead:deadhead@localhost:5432/deadhead
+TEST_DATABASE_URL=postgres://deadhead:deadhead@localhost:5432/deadhead_test
+
+# Auth (Better Auth). Secret must be at least 32 random characters;
+# generate one with: openssl rand -base64 32
+BETTER_AUTH_SECRET=change-me-to-a-long-random-string
+BETTER_AUTH_URL=http://localhost:3000
+
+# HTTP port the API server listens on
+PORT=3000
+
+# Game clock epoch (decision 0.5.9): the real instant the game clock starts,
+# and the in-game ephemeris date it maps to. Both ISO 8601, UTC.
+GAME_EPOCH_REAL_START=2026-01-01T00:00:00Z
+GAME_EPOCH_EPHEMERIS_DATE=2100-01-01T00:00:00Z

DECISIONS.md

@@ -25,3 +25,9 @@ Implementation decisions not spelled out in `memory-bank/implementation-plan.md`
 
 - **CI runs on Gitea Actions** (`.gitea/workflows/ci.yml`): install with a frozen lockfile, then typecheck, lint and test.
 - **`.pnpm-store/` is ignored** by Prettier, ESLint and git. On the Gitea runner, pnpm puts its store inside the workspace, and `prettier --check` failed on the store's files (CI run #1).
+
+## Step 1.5
+
+- **One Postgres container, two databases.** `docker-compose.yml` runs a single `postgres:18` server on port 5432 (user/password `deadhead`). The default database `deadhead` is for development; `docker/postgres/init/01-create-test-db.sql` creates `deadhead_test` the first time the data volume is created. To recreate both from scratch, run `docker compose down -v`.
+- **Env var names** in `.env.example`: `DATABASE_URL`, `TEST_DATABASE_URL`, `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL` (Better Auth's own names), `PORT`, and `GAME_EPOCH_REAL_START` plus `GAME_EPOCH_EPHEMERIS_DATE` (decision 0.5.9). The game-clock speed is not an env var; it belongs in GameConfig (rule 0.1.5).
+- **Epoch values in `.env.example` are placeholders.** The design docs do not fix an ephemeris date yet.

docker-compose.yml

@@ -0,0 +1,23 @@
+# Local development database. One Postgres server holds two databases:
+# `deadhead` for development and `deadhead_test` for automated tests.
+services:
+  postgres:
+    image: postgres:18
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: deadhead
+      POSTGRES_PASSWORD: deadhead
+      POSTGRES_DB: deadhead
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres-data:/var/lib/postgresql
+      - ./docker/postgres/init:/docker-entrypoint-initdb.d:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U deadhead -d deadhead_test"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+
+volumes:
+  postgres-data:

docker/postgres/init/01-create-test-db.sql

@@ -0,0 +1,2 @@
+-- Runs once, when the data volume is first created.
+CREATE DATABASE deadhead_test OWNER deadhead;

memory-bank/progress.md

@@ -6,4 +6,4 @@
 - [x] **Step 1.2 — Linting and formatting.** ESLint 10 + typescript-eslint + Prettier at the root (`pnpm lint`, `pnpm format`). Purity rule bans `Math.random`, `Date.now` and argument-less `new Date()` in `packages/sim` and `packages/content`; verified it fails on a planted `Math.random()`.
 - [x] **Step 1.3 — Test runner.** Vitest 5 with one project per workspace package (`pnpm test`). Trivial smoke test in `packages/sim/test/smoke.test.ts`; 1 passing.
 - [x] **Step 1.4 — Continuous integration.** Repo pushed to Gitea; `.gitea/workflows/ci.yml` runs install, typecheck, lint and test on every push (runner `homelab-runner`). Run #1 failed because Prettier scanned the runner's in-workspace `.pnpm-store/`; ignored it, and run #2 is green.
-- [ ] Step 1.5 — Local Postgres via Docker Compose
+- [x] **Step 1.5 — Local Postgres.** `docker compose up -d` starts Postgres 18 with `deadhead` (dev) and `deadhead_test` databases; connected to both with psql. `.env.example` lists the server's env vars.