docs(14-02): complete Docker & Compose for PostgreSQL plan

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.planning/REQUIREMENTS.md

@@ -13,7 +13,7 @@ Requirements for this milestone. Each maps to roadmap phases.
 - [ ] **DB-02**: All service functions use async database operations
 - [x] **DB-03**: Test infrastructure uses PGlite instead of bun:sqlite in-memory databases
 - [ ] **DB-04**: Existing SQLite data can be migrated to Postgres via a one-time script
-- [ ] **DB-05**: Docker Compose provides Postgres for local development
+- [x] **DB-05**: Docker Compose provides Postgres for local development
 
 ### Authentication
 
@@ -120,7 +120,7 @@ Which phases cover which requirements. Updated during roadmap creation.
 | DB-02 | Phase 14 | Pending |
 | DB-03 | Phase 14 | Complete |
 | DB-04 | Phase 14 | Pending |
-| DB-05 | Phase 14 | Pending |
+| DB-05 | Phase 14 | Complete |
 | AUTH-01 | Phase 15 | Pending |
 | AUTH-02 | Phase 15 | Pending |
 | AUTH-03 | Phase 15 | Pending |

.planning/ROADMAP.md

@@ -121,10 +121,10 @@ Plans:
   2. All service-level and route-level tests pass using PGlite in-memory Postgres (no SQLite test infrastructure remains)
   3. A one-time migration script converts existing SQLite data into the Postgres database without data loss
   4. Docker Compose brings up Postgres alongside the app with a single command for local development
-**Plans:** 6 plans
+**Plans:** 2/6 plans executed
 Plans:
 - [x] 14-01-PLAN.md — Schema rewrite (pg-core), DB config (postgres.js), test helper (PGlite), Drizzle config, initial migration
-- [ ] 14-02-PLAN.md — Docker Compose dev/prod + Dockerfile update for PostgreSQL
+- [x] 14-02-PLAN.md — Docker Compose dev/prod + Dockerfile update for PostgreSQL
 - [ ] 14-03-PLAN.md — All 9 services async conversion + seed + server index
 - [ ] 14-04-PLAN.md — All 9 route handlers async conversion
 - [ ] 14-05-PLAN.md — SQLite-to-Postgres data migration script
@@ -195,7 +195,7 @@ Plans:
 | 11. Candidate Ranking | v1.3 | 2/2 | Complete | 2026-03-16 |
 | 12. Comparison View | v1.3 | 1/1 | Complete | 2026-03-17 |
 | 13. Setup Impact Preview | v1.3 | 0/2 | Not started | - |
-| 14. PostgreSQL Migration | v2.0 | 1/6 | In progress | - |
+| 14. PostgreSQL Migration | v2.0 | 2/6 | In Progress|  |
 | 15. External Authentication | v2.0 | 0/? | Not started | - |
 | 16. Multi-User Data Model | v2.0 | 0/? | Not started | - |
 | 17. Object Storage | v2.0 | 0/? | Not started | - |

.planning/STATE.md

@@ -3,14 +3,14 @@ gsd_state_version: 1.0
 milestone: v1.3
 milestone_name: Research & Decision Tools
 status: executing
-stopped_at: Phase 14 plans created (6 plans, 3 waves)
+stopped_at: Completed 14-02-PLAN.md
-last_updated: "2026-04-04T10:13:29.422Z"
+last_updated: "2026-04-04T10:25:09.510Z"
-last_activity: 2026-04-04 -- Phase 14 execution started
+last_activity: 2026-04-04
 progress:
   total_phases: 8
   completed_phases: 6
   total_plans: 18
-  completed_plans: 10
+  completed_plans: 12
   percent: 0
 ---
 
@@ -26,9 +26,9 @@ See: .planning/PROJECT.md (updated 2026-04-03)
 ## Current Position
 
 Phase: 14 (postgresql-migration) — EXECUTING
-Plan: 1 of 6
+Plan: 2 of 6
-Status: Executing Phase 14
+Status: Ready to execute
-Last activity: 2026-04-04 -- Phase 14 execution started
+Last activity: 2026-04-04
 
 Progress: [----------] 0% (v2.0 milestone)
 
@@ -54,6 +54,7 @@ Key decisions made during v2.0 planning:
 - Structured UGC only — ratings and predefined fields, no freeform text until moderation
 - Separate globalItems table — not a flag on user items table
 - Single-user SQLite mode diverges at v2.0 boundary
+- [Phase 14-postgresql-migration]: Dev compose uses hardcoded Postgres credentials; production externalizes via env vars
 
 ### Pending Todos
 
@@ -66,6 +67,6 @@ None active.
 
 ## Session Continuity
 
-Last session: 2026-04-04T10:12:41.532Z
+Last session: 2026-04-04T10:25:09.507Z
-Stopped at: Phase 14 plans created (6 plans, 3 waves)
+Stopped at: Completed 14-02-PLAN.md
-Resume file: .planning/phases/14-postgresql-migration/14-01-PLAN.md
+Resume file: None

.planning/phases/14-postgresql-migration/14-02-SUMMARY.md

@@ -0,0 +1,90 @@
+---
+phase: 14-postgresql-migration
+plan: 02
+subsystem: infra
+tags: [docker, postgres, docker-compose, dockerfile]
+
+requires:
+  - phase: 14-postgresql-migration/01
+    provides: PostgreSQL schema and drizzle-pg migrations directory
+provides:
+  - Docker Compose dev file with PostgreSQL 16 for local development
+  - Production Docker Compose with Postgres + app dependency chain
+  - Lean Dockerfile without native SQLite build dependencies
+affects: [14-postgresql-migration/03, 14-postgresql-migration/04, 14-postgresql-migration/05, 14-postgresql-migration/06]
+
+tech-stack:
+  added: [postgres:16-alpine]
+  patterns: [docker-compose healthcheck with depends_on condition, externalized secrets via env vars]
+
+key-files:
+  created: [docker-compose.dev.yml]
+  modified: [docker-compose.yml, Dockerfile]
+
+key-decisions:
+  - "Dev compose uses hardcoded credentials (gearbox/gearbox) for simplicity"
+  - "Production compose externalizes POSTGRES_PASSWORD via env var"
+  - "Removed native build tools (python3/make/g++) since postgres.js is pure JS"
+
+patterns-established:
+  - "DATABASE_URL env var pattern for Postgres connection string"
+  - "service_healthy dependency for app-to-database startup ordering"
+
+requirements-completed: [DB-05]
+
+duration: 1min
+completed: 2026-04-04
+---
+
+# Phase 14 Plan 02: Docker & Compose for PostgreSQL Summary
+
+**PostgreSQL 16 Docker Compose for dev and production, lean Dockerfile without native SQLite build dependencies**
+
+## Performance
+
+- **Duration:** 1 min
+- **Started:** 2026-04-04T10:23:10Z
+- **Completed:** 2026-04-04T10:24:14Z
+- **Tasks:** 2
+- **Files modified:** 3
+
+## Accomplishments
+- Created docker-compose.dev.yml providing PostgreSQL 16 on localhost:5432 for local development
+- Rewrote docker-compose.yml with Postgres service, healthcheck, and app dependency chain for production
+- Stripped native build tools (python3/make/g++) from Dockerfile and switched to drizzle-pg migrations
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Create Docker Compose files for dev and production** - `50b451b` (feat)
+2. **Task 2: Update Dockerfile and entrypoint for PostgreSQL** - `186e74b` (feat)
+
+## Files Created/Modified
+- `docker-compose.dev.yml` - Development Postgres service with hardcoded dev credentials
+- `docker-compose.yml` - Production Postgres + app services with externalized secrets
+- `Dockerfile` - Removed native build deps, copies drizzle-pg instead of drizzle
+
+## Decisions Made
+- Dev compose uses hardcoded credentials (gearbox/gearbox) for zero-friction local development
+- Production compose externalizes POSTGRES_PASSWORD via environment variable substitution
+- No changes needed to entrypoint.sh since it already runs the generic migrate.ts script
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Docker infrastructure ready for PostgreSQL-based development and production
+- Developers can run `docker compose -f docker-compose.dev.yml up` to start local Postgres
+- Dockerfile ready to build once drizzle-pg migrations directory exists from Plan 01
+
+---
+*Phase: 14-postgresql-migration*
+*Completed: 2026-04-04*