Add Docker Compose local dev stack (fully self-contained)

forgejo_admin commented

2026-03-17 01:40:20 +00:00

Contributor

Lineage

plan-mcd-tracker → Phase 7c (Local Dev Stack + Playground Cleanup)

Repo

forgejo_admin/mcd-tracker-app

User Story

As a developer validating changes before production
I want a fully self-contained Docker Compose stack with postgres, keycloak, api, and app
So that I can run docker compose up and test the full flow locally before pushing to prod

Context

Phase 7 deployed MCD Tracker to production without local dev validation. 6 sequential hotfixes ensued. This establishes the required validation layer. The stack must be fully self-contained — zero external dependencies, works offline. Keycloak runs in dev mode with realm import. API auto-migrates on startup (Alembic). App gets hot reload via Vite dev server. Production URLs remain as fallback defaults when env vars are not set.

File Targets

Files to create:

docker-compose.yml — 4-service stack (postgres, keycloak, api, app)
dev/realm-export.json — Keycloak realm: mcd-tracker, client: mcd-tracker-app (public, PKCE), test users (testuser/testpass, testadmin/testpass, emptyuser/testpass), registration enabled
dev/seed-data.py — Test data seeder: 5-10 Denver McDonald's locations, mix of active/redeemed/expired codes, test receipts
.env.example — Documents all VITE_* env vars with local defaults

Files to modify:

src/lib/api.js — Use import.meta.env.VITE_API_URL with production fallback (https://mcd-tracker.tail5b443a.ts.net)
src/lib/keycloak.js — Use import.meta.env.VITE_KEYCLOAK_URL, VITE_KEYCLOAK_REALM, VITE_KEYCLOAK_CLIENT_ID with production fallbacks

Files NOT to touch:

Dockerfile — production build, works as-is
.woodpecker.yaml — CI pipeline, no changes needed
capacitor.config.ts — mobile config, unrelated

Acceptance Criteria

docker compose config validates without errors
docker compose up starts all 4 services
src/lib/api.js uses import.meta.env.VITE_API_URL || 'https://mcd-tracker.tail5b443a.ts.net'
src/lib/keycloak.js uses env vars with production fallbacks
.env.example documents all VITE_* vars
dev/realm-export.json contains valid Keycloak realm config
dev/seed-data.py creates test data against local API
Production builds still work (env vars unset → defaults to Tailscale URLs)

Test Expectations

docker compose config — validates YAML
docker compose up — 4 services start, postgres healthy, keycloak healthy
localhost:5173 — landing page renders
localhost:8080 — Keycloak admin console accessible
Run command: cd ~/mcd-tracker-app && docker compose config

Constraints

Production URLs are fallback defaults, NOT replaced
Keycloak uses start-dev mode (no SSL, fast startup)
API builds from ../mcd-tracker-api (sibling directory)
App mounts current directory for hot reload
Postgres data persists in named volume
Use KC_BOOTSTRAP_ADMIN_USERNAME/KC_BOOTSTRAP_ADMIN_PASSWORD (not deprecated KEYCLOAK_ADMIN)
Keycloak healthcheck: exec 3<>/dev/tcp/localhost/8080 (no curl in image)

Checklist

PR opened
Tests pass
No unrelated changes

mcd-tracker — project this affects
plan-mcd-tracker — Phase 7c

### Lineage `plan-mcd-tracker` → Phase 7c (Local Dev Stack + Playground Cleanup) ### Repo `forgejo_admin/mcd-tracker-app` ### User Story As a developer validating changes before production I want a fully self-contained Docker Compose stack with postgres, keycloak, api, and app So that I can run `docker compose up` and test the full flow locally before pushing to prod ### Context Phase 7 deployed MCD Tracker to production without local dev validation. 6 sequential hotfixes ensued. This establishes the required validation layer. The stack must be fully self-contained — zero external dependencies, works offline. Keycloak runs in dev mode with realm import. API auto-migrates on startup (Alembic). App gets hot reload via Vite dev server. Production URLs remain as fallback defaults when env vars are not set. ### File Targets Files to create: - `docker-compose.yml` — 4-service stack (postgres, keycloak, api, app) - `dev/realm-export.json` — Keycloak realm: mcd-tracker, client: mcd-tracker-app (public, PKCE), test users (testuser/testpass, testadmin/testpass, emptyuser/testpass), registration enabled - `dev/seed-data.py` — Test data seeder: 5-10 Denver McDonald's locations, mix of active/redeemed/expired codes, test receipts - `.env.example` — Documents all VITE_* env vars with local defaults Files to modify: - `src/lib/api.js` — Use `import.meta.env.VITE_API_URL` with production fallback (`https://mcd-tracker.tail5b443a.ts.net`) - `src/lib/keycloak.js` — Use `import.meta.env.VITE_KEYCLOAK_URL`, `VITE_KEYCLOAK_REALM`, `VITE_KEYCLOAK_CLIENT_ID` with production fallbacks Files NOT to touch: - `Dockerfile` — production build, works as-is - `.woodpecker.yaml` — CI pipeline, no changes needed - `capacitor.config.ts` — mobile config, unrelated ### Acceptance Criteria - [ ] `docker compose config` validates without errors - [ ] `docker compose up` starts all 4 services - [ ] `src/lib/api.js` uses `import.meta.env.VITE_API_URL || 'https://mcd-tracker.tail5b443a.ts.net'` - [ ] `src/lib/keycloak.js` uses env vars with production fallbacks - [ ] `.env.example` documents all VITE_* vars - [ ] `dev/realm-export.json` contains valid Keycloak realm config - [ ] `dev/seed-data.py` creates test data against local API - [ ] Production builds still work (env vars unset → defaults to Tailscale URLs) ### Test Expectations - [ ] `docker compose config` — validates YAML - [ ] `docker compose up` — 4 services start, postgres healthy, keycloak healthy - [ ] localhost:5173 — landing page renders - [ ] localhost:8080 — Keycloak admin console accessible - Run command: `cd ~/mcd-tracker-app && docker compose config` ### Constraints - Production URLs are fallback defaults, NOT replaced - Keycloak uses `start-dev` mode (no SSL, fast startup) - API builds from `../mcd-tracker-api` (sibling directory) - App mounts current directory for hot reload - Postgres data persists in named volume - Use `KC_BOOTSTRAP_ADMIN_USERNAME`/`KC_BOOTSTRAP_ADMIN_PASSWORD` (not deprecated KEYCLOAK_ADMIN) - Keycloak healthcheck: `exec 3<>/dev/tcp/localhost/8080` (no curl in image) ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `mcd-tracker` — project this affects - `plan-mcd-tracker` — Phase 7c