Learn Docker by doing — in a real terminal, in your browser.

DockerMissions is a fully local, browser-based training game for Docker. Each mission gives you a live shell, a clear objective, and automatic validation. No cloud. No costs. No copy-pasting from a blog post.

54 progressive challenges across 8 modules — complete beginner to production patterns.

Design and implementation by: Fatemeh

• 🐳 54 missions across 8 modules — containers, images, networks, volumes, Compose, security, registries, and advanced Docker
• 🏆 XP & progression system — earn points, unlock levels, rise through operator tiers
• 💡 Progressive hints — reveal only what you need, with XP deduction after the first hint
• ✅ Instant automated validation — click Check Mission and get a real result in seconds
• 🔍 Smart error analysis — detects syntax mistakes and wrong flag ordering with a corrected example
• 🖥️ In-browser terminal — real bash session connected to a live Docker environment
• 🏅 Badges — awarded per module completion and XP milestones
• 📊 Leaderboard — track top pilots by XP
• 💾 Offline player profiles — no account needed, progress saved locally

git clone <repo-url>
cd dockermissions

# Install dependencies
cd backend && npm install && cd ..
cd frontend && npm install && cd ..

# Generate mission data
node scripts/generate-missions.mjs

# Start both services
./start.sh

Open http://localhost:5173, enter a player name, and pick your first mission.

1. Open http://localhost:5173
2. Enter a player name in the right panel to start your offline profile
3. Select a mission from the campaign map on the left
4. Read the briefing — understand the objective and starting state
5. Use the terminal — run real Docker commands to complete the mission
6. Click Check Mission — automated validation runs against the live Docker state
7. Earn XP and unlock the next level

When validation fails, DockerMissions analyses the commands you typed and flags common mistakes:

Command issue detected:
Flags after the image name are passed to the container, not Docker.
  You wrote:  docker run -d nginx --name webserver
  Move --name before the image name.
  Example:    docker run -d --name webserver nginx

Detected patterns include:

• Docker flags placed after the image name
• Wrong -p HOST:CONTAINER format
• Missing -d flag when detached mode is required
• docker exec without -it when opening a shell
• docker build without a -t tag

Logs go to tmp/logs/backend.log and tmp/logs/frontend.log.

dockermissions/
├── start.sh / stop.sh / restart.sh   ← service management
├── backend/
│   ├── missions/data/                 ← generated mission JSON (54 levels)
│   └── src/
│       ├── data/                      ← offline player progress (JSON on disk)
│       ├── missions/                  ← mission loader and parser
│       ├── sandbox/                   ← session and workspace lifecycle
│       ├── terminal/                  ← WebSocket PTY relay (node-pty)
│       ├── validation/                ← mission validation + error analysis
│       └── routes/                    ← Express API routes
├── frontend/
│   └── src/
│       ├── components/                ← UI components (terminal, briefing, hints…)
│       ├── api/                       ← typed API clients
│       ├── pages/                     ← MissionPage layout
│       ├── store/                     ← Zustand game state
│       └── styles/                    ← global CSS (dark terminal theme)
├── docker/
│   └── sandbox/                       ← sandbox Dockerfile
├── modules/                           ← source-of-truth mission specs (Markdown)
│   ├── module_01_basics.md
│   ├── module_02_images_dockerfile.md
│   ├── module_03_networking.md
│   ├── module_04_volumes_storage.md
│   ├── module_05_docker_compose.md
│   ├── module_06_security.md
│   ├── module_07_registry.md
│   └── module_08_advanced.md
├── scripts/
│   └── generate-missions.mjs          ← parse modules/ → backend/missions/data/
├── GAME_PLAN.md                       ← full design document
└── AI_IMPLEMENTATION_PROMPT.md        ← implementation spec for AI assistants

After editing any file in modules/, regenerate the mission JSON:

node scripts/generate-missions.mjs

Then restart the backend to pick up the changes.

• React 18 + TypeScript + Vite
• xterm.js (terminal emulator with PTY resize support)
• Zustand (state management)
• Inter + JetBrains Mono (via Google Fonts)

• Node.js + Express + TypeScript (ESM)
• node-pty (real PTY, not pipe — gives a proper interactive shell)
• ws (WebSocket server)
• File-backed JSON store (no database required)

• Host Docker socket for live container/image/network/volume validation
• Per-session workspace directories with automatic cleanup (30-minute TTL)
• Command log with syntax analysis for actionable error messages

To add or change missions:

1. Edit the relevant file in modules/
2. Regenerate: node scripts/generate-missions.mjs
3. Test the mission flow in the UI

To change validation logic:

• Edit backend/src/validation/ValidationEngine.ts
• All check types are documented in GAME_PLAN.md

To report a bug or suggest a new mission:

• Open an issue with the mission ID and what you expected vs. what happened

If DockerMissions helped you learn Docker:

• 🌟 Star this repo — helps others discover it
• 🐛 Open an issue — report bugs or suggest new levels
• 🤝 Contribute — new missions, validation checks, UI improvements

MIT License.