learn-docker-k8s-game

# Learn Docker & K8s Game

> Skill by [ara.so](https://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

```bash
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
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:

```yaml
# .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:

```bash
# 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:

```bash
# 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)

```yaml
# 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)

```yaml
# 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
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

```bash
# 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"**
```bash
# macOS
open -a Docker

# Linux
sudo systemctl start docker
sudo usermod -aG docker $USER  # then log out and back in
```

**"verify.sh permission denied"**
```bash
chmod +x curriculum/ch01-containers/challenges/verify.sh
```

**"Port already in use"**
```bash
# 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"**
```bash
rm .player/progress.yaml
# Then: /play to restart
```

**kubectl not found for Ch6–7**
```bash
# 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
```