Learn Docker & K8s Game
Skill by
ara.so
— Daily 2026 Skills collection.
An open-source, AI-driven interactive learning game that teaches Docker, Linux, networking, and Kubernetes through a story-driven simulation. No web app, no video courses — just you, your AI editor, a terminal, and the chaotic coffee startup NoCappuccino Inc.
How It Works
The game runs entirely inside your AI editor. Markdown prompt files in this repo act as the game engine. When a user says "let's play," the AI reads
AGENTS.md
(or the editor-specific entry point), becomes "Sarah" (the mentor character), and walks the learner through real Docker/K8s scenarios using their actual terminal.
User says "let's play"
→ AI reads AGENTS.md + engine/rules.md + engine/narrator.md
→ AI becomes Sarah, the senior DevOps mentor
→ Story begins: Dave broke staging, fix it with containers
→ Lessons → Challenges → verify.sh → next chapter
Installation
git
clone https://github.com/ericboy0224/learn-docker-and-k8s.git
cd
learn-docker-and-k8s
Open the directory in your AI editor, then type:
"let's play"
Prerequisites
Requirement
Chapters
Notes
Docker
Ch 1–7
Required
Docker Compose v2
Ch 1–7
Required
kubectl
Ch 6–7
Optional
kind
Ch 6–7
Optional
AI Editor
All
Claude Code, Cursor, Windsurf, Copilot, Cline, Codex, Gemini CLI
Environment Check
bash
engine/environment-check.sh
This verifies Docker, Docker Compose, and optional Kubernetes tools are installed and running.
Editor Entry Points
Each AI editor reads a different config file automatically:
Editor
Entry File
Claude Code
CLAUDE.md
Cursor
.cursorrules
Windsurf
.windsurfrules
Cline / Roo Code
.clinerules
GitHub Copilot
.github/copilot-instructions.md
Gemini CLI
GEMINI.md
All others
AGENTS.md
The AI editor will read the appropriate file on startup and load game context from
engine/
and
curriculum/
.
Game Commands
Type these naturally in your AI editor chat:
/play — start or resume the game
/env-check — verify Docker/K8s setup before starting
/progress — view save file (.player/progress.yaml)
/hint — progressive hint (3 levels: nudge → direction → near-answer)
/verify — check your challenge solution
/next — advance to next lesson or challenge
/skip-to
.player/progress.yaml (example structure)
player : name : "" started_at : "" current : chapter : 1 lesson : 2 challenge : 1 completed : chapters : [ ] challenges : [ ] hints_used : 0 Challenge Verification Scripts Each challenge has a verify.sh that the AI runs to check the learner's work:
curriculum/ch01-containers/challenges/verify.sh (example pattern)
!/bin/bash
set -e echo "🔍 Checking Chapter 1 Challenge..."
Check container is running
if docker ps --filter "name=learn-api" --filter "status=running" | grep -q "learn-api" ; then echo "✅ Container 'learn-api' is running" else echo "❌ Container 'learn-api' not found or not running" exit 1 fi
Check port mapping
if docker inspect learn-api | grep -q '"HostPort": "8080"' ; then echo "✅ Port 8080 is mapped correctly" else echo "❌ Port mapping incorrect — expected 8080:8080" exit 1 fi
Check endpoint responds
if curl -sf http://localhost:8080/health
/dev/null ; then echo "✅ API is responding on port 8080" else echo "❌ API not responding — check the container logs" exit 1 fi echo "" echo "🎉 Challenge complete! Sarah is proud of you." Real Docker Commands Used in the Game The game teaches these patterns through hands-on challenges:
Ch1 — Run a container with port mapping
docker run -d --name learn-api -p 8080 :8080 my-api-image
Ch2 — Multi-stage build to reduce image size
docker build -t learn-api:optimized . docker images learn-api
compare sizes
Ch3 — Named volume for persistence
docker volume create learn-beans-data docker run -d -v learn-beans-data:/app/data --name learn-db postgres:15
Ch3 — Bind mount for development
docker run -d -v $( pwd ) /src:/app/src --name learn-dev my-app
Ch4 — Custom bridge network
docker network create learn-coffee-net docker run -d --network learn-coffee-net --name learn-api my-api docker run -d --network learn-coffee-net --name learn-db postgres:15
Ch5 — Docker Compose
docker compose up -d docker compose ps docker compose logs -f api docker compose down -v
Ch6 — Kubernetes basics
kubectl apply -f curriculum/ch06-k8s-intro/manifests/ kubectl get pods -l app = learn-api kubectl rollout status deployment/learn-api
Ch7 — Horizontal Pod Autoscaler
kubectl apply -f curriculum/ch07-k8s-production/hpa.yaml kubectl get hpa learn-api-hpa Example Docker Compose (Ch5 Pattern)
curriculum/ch05-compose/docker-compose.yml (game example)
version : "3.9" services : api : build : ./api container_name : learn - api ports : - "8080:8080" environment : - DATABASE_URL=postgresql : //user : $ { DB_PASSWORD } @db : 5432/nocappuccino depends_on : db : condition : service_healthy networks : - learn - coffee - net db : image : postgres : 15 - alpine container_name : learn - db volumes : - learn - beans - data : /var/lib/postgresql/data environment : - POSTGRES_PASSWORD=$ { DB_PASSWORD } - POSTGRES_DB=nocappuccino healthcheck : test : [ "CMD-SHELL" , "pg_isready -U postgres" ] interval : 10s timeout : 5s retries : 5 networks : - learn - coffee - net volumes : learn-beans-data : networks : learn-coffee-net : driver : bridge Note: DB_PASSWORD is read from a .env file — never hardcoded. Example Kubernetes Manifests (Ch6–7 Pattern)
curriculum/ch06-k8s-intro/manifests/deployment.yaml
apiVersion : apps/v1 kind : Deployment metadata : name : learn - api labels : app : learn - api spec : replicas : 2 selector : matchLabels : app : learn - api template : metadata : labels : app : learn - api spec : containers : - name : api image : learn - api : latest ports : - containerPort : 8080 env : - name : DB_PASSWORD valueFrom : secretKeyRef : name : learn - db - secret key : password readinessProbe : httpGet : path : /health port : 8080 initialDelaySeconds : 5 periodSeconds : 10
apiVersion : v1 kind : Service metadata : name : learn - api - svc spec : selector : app : learn - api ports : - port : 80 targetPort : 8080 type : ClusterIP Cleanup Remove all game-created Docker resources safely (uses learn- prefix convention): bash engine/cleanup.sh Or via AI editor: /cleanup This removes containers, images, volumes, and networks prefixed with learn- . It never touches your other Docker resources. Contributing
Fork and clone
git clone https://github.com/YOUR_USERNAME/learn-docker-and-k8s.git
Key contribution areas:
1. New challenges → curriculum/chXX-*/challenges/
2. New chapters → curriculum/ch08-helm/, ch09-argocd/, etc.
3. Fix verify.sh → make sure exit codes are correct (0=pass, 1=fail)
4. New AI editor → add entry point file + update AGENTS.md
5. Translations → keep technical terms (Docker, kubectl) in English
Each chapter follows this structure: chXX-topic/ ├── README.md # Story hook + learning objectives ├── lessons/ │ ├── 01-concept.md # Teaching content │ ├── 02-concept.md │ └── 03-concept.md ├── challenges/ │ ├── README.md # Challenge instructions │ └── verify.sh # Auto-verification script (chmod +x) └── quiz.md # 5 questions for /skip-to gate Troubleshooting "Docker daemon not running"
macOS
open -a Docker
Linux
sudo systemctl start docker sudo usermod -aG docker $USER
then log out and back in
"verify.sh permission denied" chmod +x curriculum/ch01-containers/challenges/verify.sh "Port already in use"
Find what's using port 8080
lsof -i :8080
or
docker ps
check if a previous learn-* container is still running
bash engine/cleanup.sh "AI isn't staying in character" Remind it: "You are Sarah from NoCappuccino. Read engine/narrator.md and continue the game." "Progress file is corrupted" rm .player/progress.yaml
Then: /play to restart
kubectl not found for Ch6–7
Install kind for local Kubernetes
brew install kind kubectl
macOS
or
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.22.0/kind-linux-amd64 chmod +x kind && sudo mv kind /usr/local/bin/kind
Create a local cluster
kind create cluster --name learn-k8s