rootnode-academy/docs/ROOT_FOUNDATIONS_LAB_STRATEGY.md

ROOT Foundations Lab Strategy

Phase 6D §7/§10 — what the existing disposable Lab can safely teach for ROOT 01-04, evaluated by actually reading backend/server.js and testing inside a real container, not assumed.

1. The scenario engine is already generic — no new activity type needed

POST /api/scenarios/:id/setup and POST /api/scenarios/:id/validate (backend/server.js) run setup_commands[].command / validation.commands[].command through runCommand(), which is a bare child_process.exec(cmd) — an arbitrary shell command string, checked against expected_output by checkMatch() (exact/contains/not_contains/regex). Nothing about this is Kubernetes-specific. Every existing scenario just happens to write kubectl ... as its command string. isolation_type (shared_namespace etc.) is pure descriptive metadata — grepped across the entire backend and frontend, it gates no actual behavior.

This means the existing lab activity type (module_activities.activity_type = 'lab', completion_behavior = 'auto_scenario') and the existing scenarios/data/*.json format already fully support Linux, networking-inspection, and Git exercises with real, deterministic validation — a scenario file with "command": "test -f /root/lab/notes.txt && echo exists" is exactly as valid as one with "command": "kubectl get pod ...". No shell_lab/git_lab/ container_lab activity type is built or needed. The speculative multi-type model the authorization raised as a possibility is unnecessary — it would duplicate a generic mechanism that already exists.

The only wrinkle: runCommand does not pass a cwd, so every command runs wherever the backend process's cwd is; multi-step Linux/Git scenarios must cd /root/lab-<id> && ... inside each command string (exactly how a real student would chain commands), not rely on shell state persisting between setup and validate calls beyond what the filesystem/git/process state itself carries.

2. What the Lab image already contains (verified from the real Dockerfile)

Ubuntu 22.04 base with curl wget git vim nano jq bash-completion iproute2 iptables iputils-ping procps htop mount kmod python3 nginx already installed, plus k3s (bundling kubectl/crictl/containerd) started by scripts/entrypoint.sh. The student terminal execs into this same container via node-pty — there is no separate "Linux sandbox," it's the same shell k3s runs in.

Already usable with zero image changes: shell navigation, file manipulation (cp/mv/rm/ cat/grep/pipes/redirection), process inspection (ps/top/kill), permissions (chmod/chown/sudo — the container runs as root, so a permission-teaching scenario should useradd a second user in its setup_commands to demonstrate a real permission denial), and network inspection (ip addr/ip route/ss/ping/curl).

Missing, needed for ROOT 02 Module 5 (DNS & HTTP): dig/nslookup are NOT installed (dnsutils/bind9-dnsutils is absent from the current package list). This is a genuinely small, justified Dockerfile addition (one more apt-get install package, same risk class as everything else already there) — not a new mechanism. curl alone already covers the HTTP half.

3. Container runtime decision — tested, not assumed

Decision: install real Docker Engine (docker.io) inside the same already-privileged Lab container, alongside k3s, as a second independent container runtime with its own nested /var/run/docker.sock. Podman was not chosen — Docker Engine matches the actual ROOT 04 curriculum content (Docker CLI, Dockerfile, Compose terminology) and required no new privilege.

Why this doesn't weaken the security boundary: the student Lab container is already launched with Privileged: true (platform/provisioner/src/lifecycle.js — required for k3s, already the accepted threat model per docs/LAB_ARCHITECTURE.md §7: the Lab Host VM, not the container boundary, is what actually contains a student). A second container runtime running inside an already-fully-privileged guest adds no new host capability. The Lab Host's own Docker socket is never touched or exposed — the nested dockerd started inside the guest listens on its own /var/run/docker.sock inside that guest's filesystem namespace, entirely separate from the Lab Host's real Docker daemon that the Provisioner itself talks to.

Tested empirically (not assumed) against the exact production resource caps (resource-policy.yaml: 2 vCPU, 4096MB memory, 512 PIDs, Privileged: true): built rootnode-academy:test fresh from the real Dockerfile, layered docker.io on top, launched it under those exact docker run constraints, and ran real workloads inside:

Step	Result	Memory	PIDs
k3s alone, ready	✓	357MB	36
+ dockerd --storage-driver=vfs started	✓	—	—
docker run --rm hello-world	✓ passed	—	—
docker run -d -p 8080:80 nginx:alpine, curl localhost:8080	✓ 200, real HTML returned	866MB	159
docker build a real 2-line Dockerfile, docker run the result	✓ passed	884MB	160

Comfortable headroom remained in all three dimensions (884MB/4096MB, 160/512 PIDs, CPU settled after the image pull). --storage-driver=vfs was used deliberately — overlay2-on-overlay2 (the Lab Host's own overlay filesystem, nested inside another overlay driver) is a known source of instability in Docker-in-Docker setups; vfs is slower per-layer but has no such nesting hazard, and ROOT 04's exercises are small single-purpose images, not build-heavy CI workloads.

docker compose is NOT included by docker.io — Ubuntu's packaged Docker CLI does not ship the Compose v2 plugin. Fixed the same way the Dockerfile already fetches k3s: download the static docker-compose v2 binary directly (matching the existing "curl a static binary rather than add a whole package repository" pattern already used for k3s) into /usr/local/lib/docker/cli-plugins/docker-compose so docker compose works as a CLI subcommand.

What was NOT done: no change to the Provisioner, Lab Router, or Gateway. No change to HostConfig (still Privileged: true, same CPU/memory/PIDs caps as every other Lab). No mount of the Lab Host's /var/run/docker.sock into any container — verified this was never written anywhere in this phase's changes.

4. Git strategy

git is already installed. All ROOT 03 exercises use local repositories created inside the student's own Lab (git init in a scenario's setup_commands) — no Gitea account, no network credentials, no dependency on RootNode's own canonical repository ever touching a student Lab. A later module ("Remote Repositories") teaches clone/fetch/pull/push/origin conceptually and against a second local bare repository created in the same Lab (git init --bare, git remote add origin /root/lab-remote.git) to give students a genuine push/pull/clone round-trip without needing any real network service, credential, or RootNode-adjacent infrastructure — Step 9's explicit constraint.

5. Classification summary

Capability	Classification
Shell/filesystem/process/permissions exercises	SUPPORTED NOW — zero image or code change
Network inspection (ip, ss, ping, curl)	SUPPORTED NOW
DNS tooling (dig/nslookup)	REQUIRES SMALL PLATFORM EXTENSION — one apt package added to the Lab Dockerfile
Git exercises (local + local-bare-remote)	SUPPORTED NOW — zero image or code change
Docker CLI / image build / single containers	REQUIRES SMALL PLATFORM EXTENSION — docker.io + entrypoint change to start dockerd, tested and proven safe/performant above
Docker Compose	REQUIRES SMALL PLATFORM EXTENSION — static docker-compose v2 binary, same pattern as k3s's own binary fetch
A distinct shell_lab/git_lab/container_lab activity type	NOT NEEDED — the existing generic lab + scenario-JSON model already covers all of the above