feat(platform-db): add lab host and environment registry

New Phase 1 Platform database — PostgreSQL, separate from the Lab image's own
SQLite (which keeps its current students/progress data untouched, decision #2 /
correction C in docs/LAB_ARCHITECTURE.md).

Schema (platform/provisioner/migrations/):
- lab_hosts: the abstraction that keeps Docker connectivity out of code —
  endpoint (unix:// or tcp://+TLS), enabled flag. Phase 1 ships one row.
- environments: environment_id (UUID), student_id (opaque external identifier,
  no FK — students table isn't in this database yet), lab_host_id (real FK),
  status, routing_token (CSPRNG via crypto.randomBytes, opaque), container/
  network identity, resource limits, lifecycle timestamps.
- environment_events: append-only audit trail, one row per lifecycle
  transition, never logs the routing token in plaintext (see
  lifecycle.js's redact()).

File-based migration runner (db.js) matching the check-before-alter idempotency
pattern already used in the Lab image's backend/server.js, applied on every
Provisioner boot.

Resource limits and the lab_hosts seed are config files
(config/resource-policy.yaml, config/lab-hosts.seed.yaml), not database tables —
there's no admin UI to manage them via a database yet, so a DB-backed policy
table would just be a write path nothing uses.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
This commit is contained in:
2026-08-18 01:21:31 -05:00
co-authored by Claude Sonnet 5
parent 60fbf0c385
commit 62241d26d2
8 changed files with 257 additions and 0 deletions
@@ -0,0 +1,23 @@
# Phase 1 lab_hosts seed — applied to the DB at Provisioner startup (config.js
# applyLabHostsSeed), not managed via a runtime API (no host-management endpoints in Phase 1,
# matching "don't overbuild scheduling yet" — see docs/PHASE1_PLATFORM_FOUNDATION.md §4).
#
# Exactly one enabled row for Phase 1. Swapping this for a remote tcp://<lab-host-vm>:2376
# entry with TLS material is the entire code change needed to point at a real, separate Lab
# Host VM in production — see docs/LAB_ARCHITECTURE.md §1 and correction D.
lab_hosts:
- lab_host_id: dev-local
display_name: "Local development Docker socket"
endpoint: "unix:///var/run/docker.sock"
enabled: true
# Production example (not active — shown for reference; uncomment and fill in when a real
# Lab Host VM exists):
# - lab_host_id: labhost-01
# display_name: "RootNode Lab Host VM 01"
# endpoint: "tcp://10.20.30.5:2376"
# tls_ca_path: /etc/rootnode/tls/labhost-01/ca.pem
# tls_cert_path: /etc/rootnode/tls/labhost-01/cert.pem
# tls_key_path: /etc/rootnode/tls/labhost-01/key.pem
# enabled: true
@@ -0,0 +1,22 @@
# Phase 1 resource policy — config-driven, not hard-coded (decision #4).
# No specific production numbers chosen yet; target host class for planning is ~16 cores/32
# threads, 128GB RAM, SSD/NVMe. Actual per-lab limits get set by benchmarking (see
# docs/PHASE1_PLATFORM_FOUNDATION.md §8 test 9), not guessed backward from the spec sheet.
# These defaults are sized for local single-machine Phase 1 dev/testing only.
default:
cpu_limit: 2.0 # vCPUs
mem_limit_mb: 4096
pids_limit: 512
storage_limit_mb: 8192 # only enforced if the host's Docker storage driver supports
# --storage-opt size= (see known-limitations in the SOP)
idle_threshold_minutes: 30 # past this: log a warning event only
abandoned_threshold_minutes: 120 # past this: reaper destroys for real
reaper_poll_interval_seconds: 60
health_check:
path: /api/health
timeout_ms: 240000 # k3s cold start in a nested container can be slow — matches the
# ~60-attempt wait already in scripts/entrypoint.sh