feat(dev): local docker-compose stack #4

2026-05-18T20:38:02Z

sharang commented

2026-05-18 20:38:02 +00:00

What

dev/docker-compose.yml brings up Keycloak 26 (:8080) + pg-keycloak + pg-app (:5432) + Redis (:6379) + Mongo (:27017) + MinIO (:9000/9001).
dev/keycloak/realm-export.json ships the breakpilot-dev realm with two seed users, a public PKCE client for the portal (redirect URIs cover http://*.localhost:3000/*), and protocol mappers projecting tenant_id / tenant_slug / org_roles / products / plan / tenant_status claims.
make dev-up / dev-down / dev-reset / dev-logs targets on the root Makefile.
dev/README.md with first-login walkthrough.

Why

Unblock local-dev work on tenant-registry and portal without waiting for M1.2 (VMs), M0.3 (DNS), or M2.1 (prod Keycloak deploy). Per INFRASTRUCTURE.md §1, dev runs entirely on developer laptops via docker-compose — this is that compose. Lands here in orca-platform because this repo already owns the production topology this dev stack mirrors.

Linked milestone: bootstrap for M4.1 / M5.1 local work

How

Single name: breakpilot-dev compose project on its own bridge network.
Healthchecks on Keycloak / pg-keycloak / pg-app / Mongo / MinIO; Keycloak waits for pg-keycloak healthy before starting.
Realm import via start-dev --import-realm mounting realm-export.json read-only — fires on the first boot, idempotent on subsequent ups (Keycloak skips if the realm already exists).
Loopback only. No public exposure, no TLS — those are prod concerns (M0.3).
Test user has tenant_id / tenant_slug / org_roles / products / plan / tenant_status set as Keycloak user attributes. Mappers project them into every JWT, matching the production contract from PLATFORM_ARCHITECTURE.md §6 so the same portal middleware code works dev → prod.

Test plan

docker compose -f dev/docker-compose.yml config -q ✅
python3 -c 'json.load(open("dev/keycloak/realm-export.json"))' ✅
make validate (manifest TOML check) ✅ unaffected
Manual: make dev-up → realm UI shows the seed user. (Run locally once this lands — not in CI.)

Risk

Blast radius: developer laptops only. Nothing in prod touched.

What could break:

First make dev-up on a slow laptop: Keycloak import takes ~30s. The healthcheck has a 30s start_period.
Realm export format changes between Keycloak versions. Pinned to 26.0 image; will need a re-export when we bump.

Rollback plan: make dev-down -v wipes everything; revert the PR if the compose itself is broken.

Checklist

Docs updated (dev/README.md + root README.md + CHANGELOG)
Secrets — none in repo. Dev passwords are intentionally inline (keycloak-dev-pass, platform-dev-pass, etc.) since they only protect a loopback compose. Anything real lands via Infisical per PRODUCT_INTEGRATION_SPEC.md §9.4.
Tenant scoping / OpenAPI / featureFlags — n/a (no code)
CHANGELOG entry under "Added"

## What - `dev/docker-compose.yml` brings up Keycloak 26 (:8080) + pg-keycloak + pg-app (:5432) + Redis (:6379) + Mongo (:27017) + MinIO (:9000/9001). - `dev/keycloak/realm-export.json` ships the `breakpilot-dev` realm with two seed users, a public PKCE client for the portal (redirect URIs cover `http://*.localhost:3000/*`), and protocol mappers projecting `tenant_id` / `tenant_slug` / `org_roles` / `products` / `plan` / `tenant_status` claims. - `make dev-up` / `dev-down` / `dev-reset` / `dev-logs` targets on the root Makefile. - `dev/README.md` with first-login walkthrough. ## Why Unblock local-dev work on `tenant-registry` and `portal` without waiting for M1.2 (VMs), M0.3 (DNS), or M2.1 (prod Keycloak deploy). Per `INFRASTRUCTURE.md §1`, dev runs entirely on developer laptops via docker-compose — this is that compose. Lands here in `orca-platform` because this repo already owns the production topology this dev stack mirrors. Linked milestone: **bootstrap for M4.1 / M5.1 local work** ## How - Single `name: breakpilot-dev` compose project on its own bridge network. - Healthchecks on Keycloak / pg-keycloak / pg-app / Mongo / MinIO; Keycloak waits for pg-keycloak healthy before starting. - Realm import via `start-dev --import-realm` mounting `realm-export.json` read-only — fires on the first boot, idempotent on subsequent ups (Keycloak skips if the realm already exists). - Loopback only. No public exposure, no TLS — those are prod concerns (M0.3). - Test user has `tenant_id` / `tenant_slug` / `org_roles` / `products` / `plan` / `tenant_status` set as Keycloak user attributes. Mappers project them into every JWT, matching the production contract from `PLATFORM_ARCHITECTURE.md §6` so the same portal middleware code works dev → prod. ## Test plan - [x] `docker compose -f dev/docker-compose.yml config -q` ✅ - [x] `python3 -c 'json.load(open("dev/keycloak/realm-export.json"))'` ✅ - [x] `make validate` (manifest TOML check) ✅ unaffected - [ ] Manual: `make dev-up` → realm UI shows the seed user. (Run locally once this lands — not in CI.) ## Risk **Blast radius:** developer laptops only. Nothing in prod touched. **What could break:** - First `make dev-up` on a slow laptop: Keycloak import takes ~30s. The healthcheck has a 30s start_period. - Realm export format changes between Keycloak versions. Pinned to 26.0 image; will need a re-export when we bump. **Rollback plan:** `make dev-down -v` wipes everything; revert the PR if the compose itself is broken. ## Checklist - [x] Docs updated (`dev/README.md` + root `README.md` + CHANGELOG) - [x] Secrets — none in repo. Dev passwords are intentionally inline (`keycloak-dev-pass`, `platform-dev-pass`, etc.) since they only protect a loopback compose. Anything real lands via Infisical per `PRODUCT_INTEGRATION_SPEC.md §9.4`. - [ ] Tenant scoping / OpenAPI / featureFlags — n/a (no code) - [x] CHANGELOG entry under "Added"

sharang added 1 commit 2026-05-18 20:38:02 +00:00

feat(dev): local docker-compose stack

ci / shared (pull_request) Successful in 4s

Details

ci / validate (pull_request) Successful in 2s

Details

2a807d7671

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)

CODEOWNERS rules requested review from Benjamin_Boenisch 2026-05-18 20:38:02 +00:00

sharang merged commit e3a62c8113 into main

2026-05-19 09:35:03 +00:00

sharang deleted branch feat/dev-stack

2026-05-19 09:35:03 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: platform/orca-platform#4