feat(dev): local docker-compose stack

Adds dev/docker-compose.yml + dev/keycloak/realm-export.json + dev/README.md and Makefile targets so a developer can: make dev-up and get Keycloak 26 on :8080 with the breakpilot-dev realm pre-imported, plus pg-app (:5432), Redis (:6379), Mongo (:27017), and MinIO (:9000 + :9001). Seed users: test@breakpilot.dev / test — IT_ADMIN of tenant 'acme' admin@breakpilot.dev / admin — BREAKPILOT_ADMIN (platform staff) Realm includes a dev-portal public PKCE client (redirect URIs cover http://localhost:3000/* and http://*.localhost:3000/* so subdomain routing works in dev) and a dev-tenant-registry bearer-only client. Protocol mappers project tenant_id, tenant_slug, org_roles, products, plan, and tenant_status into every issued JWT — the contract portal + tenant-registry expect in prod, fronted by Keycloak attributes today. dev/ lives in orca-platform because this repo already documents the production topology that this compose mirrors. INFRASTRUCTURE.md §1 sets dev as 'docker-compose on developer laptops' — this is that compose. Refs: M0.1+ (precondition for local-dev work on tenant-registry / portal)
2026-05-18 22:37:35 +02:00
parent 8e37f65b8e
commit 2a807d7671
6 changed files with 444 additions and 1 deletions
@@ -0,0 +1,62 @@
+# Local dev stack
+
+Docker-compose that brings up just enough infrastructure to run `platform/tenant-registry` and `platform/portal` locally with a real Keycloak realm + seed user.
+
+## What's running
+
+| Service          | Port            | Purpose                                                     |
+|---|---|---|
+| Keycloak 26      | `:8080`         | OIDC provider for portal + tenant-registry                  |
+| pg-keycloak      | (internal only) | Keycloak's backing Postgres                                 |
+| pg-app           | `:5432`         | Tenant Registry's Postgres (`platform/platform/platform-dev-pass`) |
+| Redis            | `:6379`         | Session cache for portal                                    |
+| Mongo            | `:27017`        | (Future) CERTifAI data store                                |
+| MinIO            | `:9000` / `:9001` console | (Future) Compliance evidence object store         |
+
+Stack is loopback only — no public exposure, no DNS, no TLS. Tenant-registry and portal run on the **host**, not in this compose.
+
+## Run
+
+From the repo root:
+
+```bash
+make dev-up        # bring everything up; first start takes ~30s for Keycloak realm import
+make dev-down      # stop, keep volumes
+make dev-reset     # stop, wipe volumes, fresh start
+make dev-logs      # tail logs from every service
+```
+
+## First login
+
+The realm `breakpilot-dev` ships pre-imported with two users:
+
+| Email                 | Password | Role                                                         |
+|---|---|---|
+| `test@breakpilot.dev` | `test`   | IT_ADMIN of tenant `acme`, products: certifai + compliance   |
+| `admin@breakpilot.dev`| `admin`  | BREAKPILOT_ADMIN (platform staff, backstage access)          |
+
+Verify Keycloak is up: <http://localhost:8080> → click "Administration Console" → log in as `admin`/`admin-dev-pass` (master admin) → switch realm to `breakpilot-dev`.
+
+## Realm contents
+
+- **Clients:**
+  - `dev-portal` — public PKCE client used by `platform/portal`. Redirect URIs cover `http://localhost:3000/*` and `http://*.localhost:3000/*` so subdomain routing works in dev.
+  - `dev-tenant-registry` — bearer-only client used by the Go service to validate JWTs.
+- **Protocol mappers on `dev-portal`** put `tenant_id`, `tenant_slug`, `org_roles`, `products`, `plan`, and `tenant_status` claims into every issued token. The portal middleware reads these to resolve the tenant + render the dashboard. The `test@breakpilot.dev` user has these claims set as user attributes — edit the user in Keycloak admin to flip flags during dev.
+- **Realm roles** (platform-staff): `BREAKPILOT_ADMIN`, `SUPPORT_ENGINEER`, `SALES_REP`.
+
+## Reset just Keycloak
+
+If you mess up the realm and want to reimport the JSON:
+
+```bash
+docker compose -f dev/docker-compose.yml down keycloak pg-keycloak
+docker volume rm breakpilot-dev_pg-keycloak-data
+make dev-up
+```
+
+The other services' data survives.
+
+## Why this is in `orca-platform`
+
+This is the only repo that already knows the whole topology — manifests in `manifests/` reference the same images this compose runs. Keeping the dev stack here means a developer clones `orca-platform`, runs `make dev-up`, and is ready to clone the service repo they actually want to work on. Per `INFRASTRUCTURE.md §1` dev runs entirely on developer laptops via docker-compose; this is that compose file.