orca-platform/README.md

orca-platform

IaC for the Breakpilot Platform: per-VM Orca service manifests, per-env overlays, DNS zones, backup/restore tooling, and the make plan/make apply wrappers.

Part of the Breakpilot Platform. For the big picture see platform/docs: Architecture · Infrastructure · Implementation Plan

What this is

The single source of truth for which container runs on which VM in which environment. Every change to prod infrastructure should flow through this repo — never through orca deploy from a laptop.

Plane: Infra Owner: @sharang Status: pre-alpha (M1.1 — layout only; real values land per the per-milestone schedule below) Linked milestone: M1.1

Directory layout

.
├── manifests/                  # Base service.toml per VM × service (35 stubs)
│   ├── vm-edge/                Identity + Infra plane services
│   ├── vm-control/             Control plane services
│   ├── vm-data/                Data plane services
│   └── stage/                  Stage (app plane only)
├── overlays/                   # Per-env sparse deltas applied on top of manifests/
│   ├── dev/overlay.toml        no-op; dev runs docker-compose per-service
│   ├── stage/overlay.toml      include manifests/stage/, image_tag=env-stage
│   └── prod/overlay.toml       include vm-{edge,control,data}, image_tag=env-prod
├── dns/
│   └── breakpilot.com.zone.template   PowerDNS zone — body lands in M0.3
├── cluster.toml.tmpl           # Cluster-level config (acme_email, backup, ai); rendered per env
├── scripts/
│   ├── validate.sh             # `make validate`
│   ├── plan.sh                 # `make plan ENV=<env>` → .orca-out/<env>/
│   ├── apply.sh                # `make apply ENV=<env>` (no-op until M1.2)
│   └── restore-drill.sh.template   M1.3 placeholder
└── Makefile                    # validate / plan / apply / diff / clean

Run locally

IaC validation

make validate                   # check all manifests parse + have required fields
make plan ENV=stage             # resolve manifests for stage → .orca-out/stage/
make plan ENV=prod              # same for prod
make apply ENV=stage            # no-op until M1.2 stands up the Orca controller

make validate runs in CI on every PR.

Dev stack

platform/orca-platform doubles as the home for the local-dev compose stack so a developer can clone this repo, run make dev-up, and immediately work against a real Keycloak realm + Postgres / Redis / Mongo / MinIO. See dev/README.md for the full picture.

make dev-up                     # Keycloak (:8080) + Postgres (:5432) + Redis (:6379) + Mongo (:27017) + MinIO (:9000)
make dev-down                   # stop, keep volumes
make dev-reset                  # stop, wipe, fresh

Seed user: test@breakpilot.dev / test (tenant acme, products certifai + compliance).

Per-milestone fill-in schedule

Each stub manifest in manifests/ carries a header comment naming the milestone that finalises its real values. Summary:

Milestone	What it fills in
M0.3	vm-edge/powerdns-auth.toml, DNS zone body, orca-proxy routes
M1.2	VM provisioning (Terraform/OpenStack in a separate repo); brings make apply online
M1.3	Backup cron services + scripts/restore-drill.sh
M2.1	vm-edge/keycloak.toml + pg-keycloak.toml
M3.1	vm-edge/infisical.toml + pg-infisical.toml + redis-infisical.toml
M3.2	vm-control/stalwart.toml
M4.1	vm-control/tenant-registry.toml + vm-data/pg-app.toml
M5.1	vm-control/customer-portal.toml + stage equivalents
M6.x	vm-data/certifai-dashboard.toml, mongodb.toml, litellm.toml
M7.x	compliance services on vm-data + stage
M8.1	vm-control/erpnext.toml, mariadb.toml, redis-erpnext.toml
M9.1	vm-control/frappe-hd.toml

Until the milestone PR lands, the stub still parses and make validate stays green — but apply will refuse a stub that hasn't replaced its placeholder image tag (gate to be added with the first real image).

Endpoints / surface

Target	What it does
make validate	Parse + structural check (no cluster contact)
make plan ENV=<env>	Resolve manifests + overlay → .orca-out/<env>/
make apply ENV=<env>	Push to Orca controller at $ORCA_API_URL (M1.2 brings this online)
make diff ENV=<env>	Alias for plan
make clean	Remove .orca-out/

Deployment

Env	Apply path	Trigger
dev	docker-compose in each product repo	dev's machine
stage	make apply ENV=stage against the stage Orca controller	CI on merge to main + image build
prod	make apply ENV=prod against the prod Orca controller	release tag vX.Y.Z + sign-off

apply for prod will be gated by the production-promotion gate (24h stage soak + manual sign-off) per IMPLEMENTATION_PLAN.md §1.6. Wiring lands in M1.2.

Observability

• Traces, logs, metrics: SigNoz — service name per individual container
• On-call: oncall@breakpilot.com · runbooks at platform/docs/runbooks/

Contributing

See CONTRIBUTING.md. Every PR touching manifests/ MUST keep make validate green; CI enforces it.

License

Proprietary — all rights reserved. Copyright (c) 2026 Sharang Parnerkar and Benjamin Boenisch. See LICENSE.