orca-platform/dev/README.md

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:

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:

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.