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`](https://gitea.meghsakha.com/platform/docs):
> [Architecture](https://gitea.meghsakha.com/platform/docs/src/branch/main/PLATFORM_ARCHITECTURE.md) ·
> [Infrastructure](https://gitea.meghsakha.com/platform/docs/src/branch/main/INFRASTRUCTURE.md) ·
> [Implementation Plan](https://gitea.meghsakha.com/platform/docs/src/branch/main/IMPLEMENTATION_PLAN.md)

## 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](https://gitea.meghsakha.com/platform/docs/src/branch/main/IMPLEMENTATION_PLAN.md)

## 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

```bash
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`](./dev/README.md) for the full picture.

```bash
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](https://signoz.meghsakha.com) — service name per individual container
- On-call: `oncall@breakpilot.com` · runbooks at `platform/docs/runbooks/`

## Contributing

See [`CONTRIBUTING.md`](./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`](./LICENSE).