learn-docker-k8s-game

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 <N>    — jump to chapter N (triggers a quiz gate)
/cleanup        — remove all learn-* Docker resources safely

You can also speak naturally:

• "I'm stuck on the port mapping"
• "check my work"
• "what does -p do again?"
• "skip to chapter 4"

---

Curriculum Overview

Ch1 → Ch2 → Ch3 → Ch4 → Ch5 → Ch6 → Ch7

Chapter	Title	Core Skills
1	📦 It Works on My Machine	containers, images, port mapping
2	🏋️ The 2GB Espresso	multi-stage builds, layer caching, .dockerignore
3	💾 The Vanishing Beans	volumes, bind mounts, persistence
4	🔌 The Silent Grinder	DNS, bridge networks, isolation
5	🎼 The Symphony of Steam	Docker Compose, health checks, secrets
6	⎈ The Giant Roaster	Pods, Deployments, Services, self-healing
7	🔥 The Great Latte Leak	rolling updates, Secrets, HPA, chaos triage

Linux fundamentals (namespaces, cgroups, mounts) and networking (DNS, NAT, subnets, iptables) are taught contextually throughout — no dedicated lecture needed.

---

Project Structure

learn-docker-and-k8s/
├── AGENTS.md                        # Universal AI entry point
├── CLAUDE.md                        # Claude Code entry + skill definitions
├── GEMINI.md                        # Gemini CLI entry point
├── .cursorrules                     # Cursor entry point
├── .clinerules                      # Cline/Roo Code entry point
├── .windsurfrules                   # Windsurf entry point
├── .github/
│   └── copilot-instructions.md      # GitHub Copilot entry point
│
├── engine/
│   ├── rules.md                     # Teaching vs challenge mode rules
│   ├── narrator.md                  # Story, characters (Sarah/Dave/Marcus), tone
│   ├── validation.md                # How AI should verify challenge solutions
│   ├── environment-check.sh         # Pre-flight Docker/K8s check
│   └── cleanup.sh                   # Remove all learn-* resources
│
├── curriculum/
│   ├── ch01-containers/
│   │   ├── README.md                # Chapter story + learning objectives
│   │   ├── lessons/                 # 3 teaching lessons per chapter
│   │   ├── challenges/              # Hands-on tasks + verify.sh scripts
│   │   └── quiz.md                  # Skip-level assessment questions
│   ├── ch02-image-optimization/
│   ├── ch03-persistence/
│   ├── ch04-networking/
│   ├── ch05-compose/
│   ├── ch06-k8s-intro/
│   └── ch07-k8s-production/
│
└── .player/
    └── progress.yaml                # Save file — AI reads/writes this

---

The Game Engine: Key Files

engine/rules.md

Defines the two game modes:

• Teaching mode — AI explains concepts, answers questions freely
• Challenge mode — AI gives only progressive hints; never reveals the answer directly

engine/narrator.md

Defines character voices and story tone:

• Sarah — friendly senior DevOps mentor, uses coffee metaphors
• Dave — CTO who breaks things and says "just restart it"
• Marcus — PM who sets impossible deadlines ("demo is at 3")

engine/validation.md

Tells the AI how to run and interpret verify.sh scripts — it will execute them in the terminal and parse output to determine pass/fail.

.player/progress.yaml

The save file. The AI manages this automatically:

# .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