learn-docker-k8s-game

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Learn Docker & K8s Game

学习Docker与K8s的游戏

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.

技能由ara.so提供 — 2026年度每日技能合集。

这是一款开源的AI驱动交互式学习游戏，通过故事驱动的模拟场景教授Docker、Linux、网络知识和Kubernetes。无需网页应用，无需视频课程——只有你、你的AI编辑器、终端，以及状况百出的咖啡创业公司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

游戏完全运行在你的AI编辑器内部。本仓库中的Markdown提示文件充当游戏引擎。当用户输入"let's play"时，AI会读取

AGENTS.md

（或对应编辑器的专属入口文件），化身导师角色"Sarah"，通过用户的真实终端引导学习者完成真实的Docker/K8s场景任务。

用户输入"let's play"
    → AI读取AGENTS.md + engine/rules.md + engine/narrator.md
    → AI化身为资深DevOps导师Sarah
    → 故事开启：Dave搞坏了预发布环境，用容器修复它
    → 课程学习 → 挑战任务 → verify.sh验证 → 进入下一章节

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"

bash

git clone https://github.com/ericboy0224/learn-docker-and-k8s.git
cd learn-docker-and-k8s

在你的AI编辑器中打开该目录，然后输入："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

依赖	适用章节	说明
Docker	第1–7章	必须
Docker Compose v2	第1–7章	必须
kubectl	第6–7章	可选
kind	第6–7章	可选
AI编辑器	全部章节	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.

bash

bash engine/environment-check.sh

该脚本会验证Docker、Docker Compose以及可选的Kubernetes工具是否已安装并正常运行。

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/

不同的AI编辑器会自动读取对应的配置文件：

编辑器	入口文件
Claude Code	`CLAUDE.md`
Cursor	`.cursorrules`
Windsurf	`.windsurfrules`
Cline / Roo Code	`.clinerules`
GitHub Copilot	`.github/copilot-instructions.md`
Gemini CLI	`GEMINI.md`
其他编辑器	`AGENTS.md`

AI编辑器会在启动时读取对应的文件，并从

engine/

和

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"
```

你可以在AI编辑器的聊天框中自然输入这些命令：

/play           — 开始或继续游戏
/env-check      — 开始前验证Docker/K8s环境配置
/progress       — 查看存档文件(.player/progress.yaml)
/hint           — 逐级提示（3个等级：轻微引导 → 方向指引 → 接近答案）
/verify         — 检查你的挑战任务解决方案
/next           — 进入下一课或下一个挑战
/skip-to <N>    — 跳转到第N章（会触发测验门槛）
/cleanup        — 安全移除所有learn-*开头的Docker资源

你也可以用自然语言提问：

```
"我卡在端口映射这步了"
```
```
"检查我的作业"
```
```
"-p参数是干什么的来着？"
```
```
"跳转到第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.

第1章 → 第2章 → 第3章 → 第4章 → 第5章 → 第6章 → 第7章

章节	标题	核心技能
1	📦 我本地运行没问题啊	容器、镜像、端口映射
2	🏋️ 2GB大小的浓缩咖啡	多阶段构建、层缓存、.dockerignore
3	💾 消失的咖啡豆	卷、绑定挂载、数据持久化
4	🔌 沉默的研磨机	DNS、桥接网络、隔离
5	🎼 蒸汽交响乐	Docker Compose、健康检查、密钥
6	⎈ 巨型烘焙机	Pod、Deployment、Service、自愈
7	🔥 拿铁大泄漏	滚动更新、Secret、HPA、故障排查

Linux基础（命名空间、cgroups、挂载）和网络知识（DNS、NAT、子网、iptables）会在整个课程中结合上下文讲解——无需单独的理论课。

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

learn-docker-and-k8s/
├── AGENTS.md                        # 通用AI入口点
├── CLAUDE.md                        # Claude Code入口 + 技能定义
├── GEMINI.md                        # Gemini CLI入口点
├── .cursorrules                     # Cursor入口点
├── .clinerules                      # Cline/Roo Code入口点
├── .windsurfrules                   # Windsurf入口点
├── .github/
│   └── copilot-instructions.md      # GitHub Copilot入口点
│
├── engine/
│   ├── rules.md                     # 教学模式和挑战模式的规则
│   ├── narrator.md                  # 故事、角色（Sarah/Dave/Marcus）、语气设定
│   ├── validation.md                # AI验证挑战解决方案的规则
│   ├── environment-check.sh         # 启动前Docker/K8s环境检查脚本
│   └── cleanup.sh                   # 移除所有learn-*开头的资源
│
├── curriculum/
│   ├── ch01-containers/
│   │   ├── README.md                # 章节故事 + 学习目标
│   │   ├── lessons/                 # 每章3节教学课
│   │   ├── challenges/              # 实操任务 + verify.sh验证脚本
│   │   └── quiz.md                  # 跳级评估问题
│   ├── ch02-image-optimization/
│   ├── ch03-persistence/
│   ├── ch04-networking/
│   ├── ch05-compose/
│   ├── ch06-k8s-intro/
│   └── ch07-k8s-production/
│
└── .player/
    └── progress.yaml                # 存档文件 — AI会读写该文件

The Game Engine: Key Files

游戏引擎：核心文件

engine/rules.md

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

定义了两种游戏模式：

教学模式 — AI解释概念，自由回答问题
挑战模式 — AI仅提供逐级提示，永远不会直接透露答案

engine/narrator.md

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")

定义了角色语调和故事风格：

Sarah — 友好的资深DevOps导师，喜欢用咖啡相关的比喻
Dave — 总搞坏东西的CTO，口头禅是"重启一下就好了"
Marcus — 总提不可能 deadlines的PM（"3点就要演示"）

engine/validation.md

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.

告知AI如何运行和解读

verify.sh

脚本——它会在终端中执行这些脚本，解析输出判断是否通过。

.player/progress.yaml

.player/progress.yaml

The save file. The AI manages this automatically:

yaml

undefined

存档文件，AI会自动管理该文件：

yaml

undefined

.player/progress.yaml (example structure)

.player/progress.yaml（示例结构）

player: name: "" started_at: "" current: chapter: 1 lesson: 2 challenge: 1 completed: chapters: [] challenges: [] hints_used: 0

---

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

undefined

每个挑战都有对应的

verify.sh

，AI会运行该脚本检查学习者的完成情况：

bash

undefined

curriculum/ch01-containers/challenges/verify.sh (example pattern)

curriculum/ch01-containers/challenges/verify.sh（示例）

#!/bin/bash set -e

echo "🔍 Checking Chapter 1 Challenge..."

#!/bin/bash set -e

echo "🔍 正在检查第1章挑战..."

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

if docker ps --filter "name=learn-api" --filter "status=running" | grep -q "learn-api"; then echo "✅ 容器'learn-api'正在运行" else echo "❌ 未找到容器'learn-api'或容器未运行" 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

if docker inspect learn-api | grep -q '"HostPort": "8080"'; then echo "✅ 端口8080映射正确" else echo "❌ 端口映射错误 — 预期为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."

---

if curl -sf http://localhost:8080/health > /dev/null; then echo "✅ API在8080端口响应正常" else echo "❌ API未响应 — 请检查容器日志" exit 1 fi

echo "" echo "🎉 挑战完成！Sarah为你感到骄傲。"

---

Real Docker Commands Used in the Game

游戏中使用的真实Docker命令

The game teaches these patterns through hands-on challenges:

bash

undefined

游戏会通过实操挑战教你这些命令用法：

bash

undefined

Ch1 — Run a container with port mapping

第1章 — 运行带端口映射的容器

docker run -d --name learn-api -p 8080:8080 my-api-image

Ch2 — Multi-stage build to reduce image size

第2章 — 多阶段构建缩小镜像体积

docker build -t learn-api:optimized . docker images learn-api # compare sizes

docker build -t learn-api:optimized . docker images learn-api # 对比体积

Ch3 — Named volume for persistence

第3章 — 命名卷实现数据持久化

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

第3章 — 开发环境绑定挂载

docker run -d -v $(pwd)/src:/app/src --name learn-dev my-app

Ch4 — Custom bridge network

第4章 — 自定义桥接网络

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

第5章 — Docker Compose

docker compose up -d docker compose ps docker compose logs -f api docker compose down -v

Ch6 — Kubernetes basics

第6章 — Kubernetes基础

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

第7章 — 水平Pod自动扩缩容

kubectl apply -f curriculum/ch07-k8s-production/hpa.yaml kubectl get hpa learn-api-hpa

---

kubectl apply -f curriculum/ch07-k8s-production/hpa.yaml kubectl get hpa learn-api-hpa

---

Example Docker Compose (Ch5 Pattern)

Docker Compose示例（第5章模式）

yaml

undefined

yaml

undefined

curriculum/ch05-compose/docker-compose.yml (game example)

curriculum/ch05-compose/docker-compose.yml（游戏示例）

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.

---

version: "3.9"

volumes: learn-beans-data:

networks: learn-coffee-net: driver: bridge


> 注意：`DB_PASSWORD`会从`.env`文件读取——永远不要硬编码。

---

Example Kubernetes Manifests (Ch6–7 Pattern)

Kubernetes清单示例（第6-7章模式）

yaml

undefined

yaml

undefined

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

---

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.

安全移除所有游戏创建的Docker资源（遵循

learn-

前缀命名规范）：

bash

bash engine/cleanup.sh

或者在AI编辑器中输入：

/cleanup

该操作会移除所有

learn-

前缀的容器、镜像、卷和网络，不会影响你其他的Docker资源。

Contributing

贡献指南

bash

undefined

bash

undefined

Fork and clone

Fork并克隆仓库

git clone https://github.com/YOUR_USERNAME/learn-docker-and-k8s.git

git clone https://github.com/你的用户名/learn-docker-and-k8s.git

Key contribution areas:

主要贡献方向：

1. New challenges → curriculum/chXX-*/challenges/

1. 新增挑战 → curriculum/chXX-*/challenges/

2. New chapters → curriculum/ch08-helm/, ch09-argocd/, etc.

2. 新增章节 → curriculum/ch08-helm/、ch09-argocd/等

3. Fix verify.sh → make sure exit codes are correct (0=pass, 1=fail)

3. 修复verify.sh → 确保退出码正确（0=通过，1=失败）

4. New AI editor → add entry point file + update AGENTS.md

4. 适配新的AI编辑器 → 新增入口文件并更新AGENTS.md

5. Translations → keep technical terms (Docker, kubectl) in English

5. 翻译 → 技术术语（Docker、kubectl）保留英文


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

---


每个章节遵循以下结构：

chXX-主题/ ├── README.md # 故事引子 + 学习目标 ├── lessons/ │ ├── 01-concept.md # 教学内容 │ ├── 02-concept.md │ └── 03-concept.md ├── challenges/ │ ├── README.md # 挑战说明 │ └── verify.sh # 自动验证脚本（需授予执行权限chmod +x） └── quiz.md # /skip-to跳转门槛的5道测验题

---

Troubleshooting

问题排查

"Docker daemon not running"

bash

undefined

"Docker daemon未运行"

bash

undefined

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

undefined

sudo systemctl start docker sudo usermod -aG docker $USER # 执行后退出并重新登录


**"verify.sh权限被拒绝"**
```bash
chmod +x curriculum/ch01-containers/challenges/verify.sh

"端口已被占用"

bash

undefined

Find what's using port 8080

查找占用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

docker ps # 检查是否有之前的learn-*容器还在运行 bash engine/cleanup.sh


**"AI没有保持角色设定"**
提醒它：`"你是NoCappuccino的Sarah，读取engine/narrator.md继续游戏。"`

**"进度文件已损坏"**
```bash
rm .player/progress.yaml

Then: /play to restart

然后输入：/play 重新开始


**kubectl not found for Ch6–7**
```bash


**第6-7章提示kubectl未找到**
```bash

Install kind for local Kubernetes

安装kind用于本地运行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

undefined

kind create cluster --name learn-k8s

undefined