learn-docker-k8s-game

$27

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