ced4568andClaude Sonnet 5
c89e39c5ee
New internal component (platform/gateway/) — the only student-facing path to
disposable Lab environments. Browsers never reach a Lab container, the
Provisioner, or Postgres directly.
Routes:
- /api/environment/{status,launch,reset} — student-facing glue (X-Student-Id),
calls the Provisioner internally (shared secret never reaches the browser).
Reuses an existing non-terminal environment on launch rather than always
provisioning a new one; reset destroys+recreates the same environment row.
- /lab/<token>/* — HTTP+WS proxy into that one student's Lab container,
resolved by opaque routing token via a new Provisioner endpoint
(GET /environments/by-token/:token). No raw container IP/port ever reaches
the browser. Rejects invalid tokens (404), unready environments (202/503),
and cross-student access via an optional ?sid= ownership check (403) — see
docs/PHASE2A_GATEWAY_AND_STUDENT_FLOW.md "Security" for why token-alone,
student-id-alone, and env-id-alone are each individually insufficient and
this is explicitly pilot-grade, not production auth.
- everything else — proxied to the persistent identity/curriculum backend
(roster, login, curriculum, progress, platform-shell frontend), or to the
student's own Lab if a valid lab-session cookie is present.
Routing design note: the existing Lab UI makes root-relative calls
(fetch('/api/scenarios'), the /shell-ws WebSocket) with no idea it might be
served under a /lab/<token>/ prefix — preserving that UI unmodified was a
hard requirement. Solved with an HttpOnly, SameSite=Lax cookie set on the
first /lab/<token>/ response: every later request from that browser carries
it, so the unmodified Lab UI's own unprefixed calls resolve correctly once a
student has navigated into a lab session, with zero changes to its code.
/api/environment/* is explicitly exempted from cookie-based routing so it
never gets hijacked by an active lab session.
Also added platform/docker-compose.dev.yml (the full local stack: Postgres +
egress-proxy + Provisioner + a persistent "identity" instance + Gateway) and
platform/README.md tying the components together. The "identity" instance
required an explicit `network_mode: bridge` — under Compose's own
auto-created bridge network, k3s failed at startup with "no default routes
found in /proc/net/route"; documented as a known limitation, not fully
root-caused.
Found and fixed during testing: express.json() applied globally broke
http-proxy's re-streaming of proxied POST bodies (e.g. POST /api/roster hung
forever, since the body had already been consumed by the parser before
proxy.web() tried to forward it). Removed — none of the Gateway's own routes
actually need a parsed body.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
2.5 KiB
2.5 KiB
RootNode Academy — Platform
The full multi-student platform, layered on top of the unmodified Lab image at the repo root. Start here, then go to the component you need:
provisioner/— Postgres-backed environment registry and lifecycle. Design:docs/LAB_ARCHITECTURE.md,docs/PHASE1_PLATFORM_FOUNDATION.md. Operational reference:provisioner/README.md.gateway/— the only student-facing path to a Lab (HTTP + WebSocket proxy, environment-aware routing, student identity glue). Design:docs/PHASE2A_GATEWAY_AND_STUDENT_FLOW.md.egress-proxy/— shared allowlisting proxy every Lab's outbound traffic passes through.docker-compose.dev.yml— the full stack (Postgres, egress proxy, Provisioner, a persistent "identity" instance, Gateway) on one machine. This is the Phase 1/2A local dev exception — production is the two-VM Proxmox split described indocs/LAB_ARCHITECTURE.md§1.
Running the full stack locally
cd platform
echo "PROVISIONER_SHARED_SECRET=$(openssl rand -hex 32)" > .env
docker compose -f docker-compose.dev.yml build
docker compose -f docker-compose.dev.yml up -d
Wait for identity to boot (it runs a real k3s cluster, same as any Lab — check with
curl http://localhost:7554/api/health), then the whole platform is reachable at
http://localhost:4200 (the Gateway) — that's the one origin a student's browser would use.
Tests
provisioner/test/run.js— fast, isolated Provisioner tests (network/container/firewall mechanics, no Gateway/identity involved). Run againstprovisioner/docker-compose.dev.yml.test/e2e-phase2a.js— slow, full-stack tests against the compose file above: roster → login → curriculum → launch → Gateway routing → cross-student rejection → progress relay → reset. Real k3s boots, budget several minutes. Run whenever the Gateway, Provisioner API surface, or the identity backend's progress/roster/curriculum routes change.
Neither substitutes for the manual real-Lab-image checks (node-pty, terminal WebSocket,
kubectl, scenario validation) in docs/PHASE2A_GATEWAY_AND_STUDENT_FLOW.md §8 — those need a
browser-equivalent client and aren't automated here.
Known limitations
See provisioner/README.md (Phase 1) and docs/PHASE2A_GATEWAY_AND_STUDENT_FLOW.md §9
(Phase 2A) for the full, honest lists — including the identity service's network_mode: bridge requirement and its unused-k3s resource cost, both flagged as real, not swept under
the rug.