KubeKosh — RootNode Academy Edition

A browser-based Kubernetes lab for hands-on learners. Real K3s. Real kubectl. Instant validation. No cloud account, no local cluster.

---

Attribution. This is a branded, modified fork of the excellent zeborg/kubekosh, licensed under Apache 2.0. RootNode Academy adds custom scenarios, branding, and multi-student deployment tooling on top of the upstream project. Original copyright and license notices are preserved in LICENSE. Modified files are marked per Apache 2.0 §4. Full credit to the original author for the core platform.

---

What It Is

KubeKosh runs a real single-node K3s cluster inside one Docker container and pairs it with a browser terminal and automated scenario validation. A learner opens a tab, gets a live cluster, runs real kubectl, and clicks Validate to check their work against actual cluster state.

In the RootNode Academy curriculum this is the capstone rung — the Kubernetes & DevOps track that sits on top of the Linux / Git / Docker foundations. It is aimed at the advanced learner (roughly 14+), not the absolute beginner.

---

Quick Start

Prerequisite: Docker

docker run -itd --name kubekosh --privileged -p 7554:80 ced4568/kubekosh:latest

Open http://localhost:7554 and wait ~30s for the Cluster Ready indicator to turn green.

--privileged is required — K3s needs kernel namespaces and cgroups. Do not expose this container directly to the public internet. It is a teaching sandbox. Multi-student exposure is handled by the deployment layer below, not by publishing the raw container.

Persist Progress

docker run -itd --name kubekosh --privileged -p 7554:80 \
  -v <host_dir>:/data ced4568/kubekosh:latest

Progress is stored in SQLite at /data/progress.db. Mount a host directory to /data to keep progress across restarts — one volume per student.

Build From Source

docker build -t kubekosh .
# multi-platform
docker buildx build --platform linux/amd64,linux/arm64 -t kubekosh .

---

What's Inside

Bundle	Focus	Exam Mode
🌱 Kubernetes Basics	Core concepts	60 min
🧑‍✈️ Kubernetes Administrator	CKA	120 min
🛠️ Kubernetes Developer	CKAD	120 min
🛡️ Kubernetes Security	CKS	120 min

Scenario types

• Task — hands-on challenge in the live terminal; Validate auto-checks cluster state.
• MCQ — multiple choice with a detailed explanation on submission.

Custom RootNode Academy scenarios live alongside upstream ones in scenarios/data/ and are grouped into bundles in scenarios/bundles/. See scenarios/SCHEMA.md.

---

Architecture

flowchart TD
    subgraph Container["Single Docker Image (--privileged)"]
        NGINX["nginx :80 — reverse proxy"]
        FE["Frontend<br/>React + Vite + xterm.js"]
        BE["Backend<br/>Node / Express + node-pty (WebSocket PTY)"]
        K3S["K3s<br/>single-node in-container cluster"]
        DB[("SQLite<br/>/data/progress.db")]

        NGINX --> FE
        NGINX --> BE
        BE -->|kubectl / PTY| K3S
        BE --> DB
    end

    Student["Learner browser"] -->|:7554| NGINX

Component	Technology
Frontend	React + Vite, xterm.js
Backend	Node.js / Express, node-pty WebSocket PTY
Cluster	K3s (single-node, in-container)
Proxy	nginx on port 80, mapped to host 7554
Storage	SQLite (better-sqlite3) at /data/progress.db

Everything runs inside one image managed by scripts/entrypoint.sh.

---

Multi-Student Deployment (RootNode Academy addition)

The upstream project assumes one learner, one container — this image is still exactly that, unmodified except for a node-pty build fix (see docs/PHASE2A_GATEWAY_AND_STUDENT_FLOW.md §1). RootNode Academy multiplies it into a real platform via separate provisioning and gateway layers rather than changing the image itself:

• platform/provisioner/ — Postgres-backed environment registry, per-student Docker networking, firewall-enforced egress, idle reaper (docs/PHASE1_PLATFORM_FOUNDATION.md).
• platform/api/ — lightweight Platform API: students, cohorts, curriculum, progress, scenario attempts, persistent student/instructor sessions, per-instructor accounts (RBAC: owner/admin/instructor), audit log, instructor/admin control plane. No k3s, no --privileged (docs/PHASE2B_ADMIN_AND_PLATFORM_DATA.md, docs/PHASE3A_IDENTITY_AND_INSTRUCTOR_ACCESS.md).
• platform/gateway/ — the only student-facing path to a Lab: resolves identity from a server-controlled, persistent session cookie (not a client-suppliable header/param), proxies HTTP/WebSocket into that one student's container, never a raw container IP/port (docs/PHASE2A_GATEWAY_AND_STUDENT_FLOW.md, session model in docs/PHASE3A_IDENTITY_AND_INSTRUCTOR_ACCESS.md §3).
• The student flow (roster login → curriculum dashboard → Launch Lab → Lab session → Reset/Recreate) lives in frontend/src/platform/; the instructor/admin portal (per-instructor login, cohorts, students, instructor accounts, audit log, classroom "Prepare Labs," environment controls) lives in frontend/src/admin/ at the /admin route — both small additions alongside the existing, unmodified Lab UI, not a rewrite of it.

Never publish the raw privileged container — front it with isolation (that's what the Gateway is). The one-container docker run --privileged -p 7554:80 ... command above stays supported for local development and scenario authoring; it is not how this gets deployed to real students.

Key properties of the platform (not this image):

• One container per student, its own Docker network, its own firewall chain — never a shared cluster between learners. Verified with two simultaneous students: separate clusters, separate progress, no cross-access.
• Progress/identity live outside the disposable container, in the Platform API's own PostgreSQL (authoritative as of Phase 2B) — destroying or recreating a student's Lab never loses their academic record. Verified with a full class-sized (3-student) cohort workflow: provision, complete different scenarios, reset one student's Lab, destroy all Labs after class — progress survives every step.
• Instructors sign in with their own account (no shared password) and manage cohorts, students, curriculum assignment, and classroom Lab prep (provision an entire cohort before class, verify readiness, destroy Labs after) from /admin — no manual database, Docker, or Kubernetes access needed. Owners manage instructor accounts and roles; every instructor/admin action is recorded in an audit log.
• Sessions (student and instructor) are Postgres-backed and survive a Platform API restart — verified by actually restarting it mid-session and confirming access still works.
• CPU/memory/PID/storage limits are enforced per container, config-driven.
• Egress is restricted to an allowlisted proxy at the firewall layer, not left open.
• Idle/abandoned environments are automatically cleaned up, and a student can launch a fresh one and keep going without losing progress.

Production topology and what's built vs. not yet: docs/LAB_ARCHITECTURE.md, docs/PHASE1_PLATFORM_FOUNDATION.md, docs/PHASE2A_GATEWAY_AND_STUDENT_FLOW.md, docs/PHASE3A_IDENTITY_AND_INSTRUCTOR_ACCESS.md.

---

Repository Layout

scenarios/
├── data/         # one JSON file per scenario  -> <scenario-id>.json
├── bundles/      # one JSON file per bundle     -> <bundle-id>.json
└── SCHEMA.md     # full schema reference

backend/  server.js      # Express API + WebSocket PTY
frontend/ src/           # React + Vite SPA
scripts/  entrypoint.sh  # container startup (k3s -> API -> nginx)
          nginx.conf     # reverse-proxy config

---

Authoring Scenarios

Each scenario is one JSON file in scenarios/data/; each bundle is one JSON file in scenarios/bundles/. See scenarios/SCHEMA.md for the full schema.

Task checklist

• validation.commands — idempotent kubectl only
• setup_commands / teardown_commands — kubectl or native Ubuntu only

MCQ checklist

• correct_option must match an options[].id
• always include an explanation

Hot-reload while authoring (no rebuild):

docker run --rm -itd --privileged -p 7554:80 --name kubekosh \
  -v $PWD/scenarios:/app/scenarios ced4568/kubekosh:latest
curl -X POST http://localhost:7554/api/cache/reload

---

License

Apache 2.0 — see LICENSE. Original work © the zeborg/kubekosh authors. Modifications © RootNode Academy / Chase Dumphord (ced4568).