dojo.md 0.2.0 → 0.2.1

package/courses/docker-container-debugging/scenarios/level-1/docker-logs-debugging.yaml

@@ -0,0 +1,67 @@
+meta:
+  id: docker-logs-debugging
+  level: 1
+  course: docker-container-debugging
+  type: output
+  description: "Debug with Docker logs — learn to use docker logs, docker inspect, and docker exec for systematic container troubleshooting"
+  tags: [Docker, logs, inspect, exec, debugging-commands, beginner]
+
+state: {}
+
+trigger: |
+  Your containerized web application is running but returning 500
+  errors. You need to figure out what's wrong.
+
+  $ docker ps
+  CONTAINER ID   IMAGE          STATUS         PORTS                  NAMES
+  a1b2c3d4e5f6   webapp:v2.1    Up 3 minutes   0.0.0.0:8080->3000/tcp api
+
+  $ curl http://localhost:8080/health
+  {"status":"error","message":"database connection failed"}
+
+  Step 1 — Check logs:
+  $ docker logs api
+  [2025-12-01T10:00:00] Starting server on port 3000
+  [2025-12-01T10:00:01] Error: connect ECONNREFUSED 172.17.0.5:5432
+  [2025-12-01T10:00:02] Retrying database connection (1/5)...
+  [2025-12-01T10:00:03] Error: connect ECONNREFUSED 172.17.0.5:5432
+  [2025-12-01T10:00:08] All retry attempts failed. Running in degraded mode.
+
+  Step 2 — Inspect the container:
+  $ docker inspect api --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}'
+  172.17.0.3
+
+  $ docker inspect api --format='{{json .Config.Env}}' | jq
+  ["DATABASE_URL=postgres://user:pass@172.17.0.5:5432/mydb", "NODE_ENV=production"]
+
+  The DATABASE_URL points to 172.17.0.5 but is that IP still valid?
+
+  Step 3 — Exec into the container:
+  $ docker exec -it api sh
+  /app $ ping 172.17.0.5
+  PING 172.17.0.5: 56 data bytes
+  --- 172.17.0.5 ping statistics ---
+  3 packets transmitted, 0 received, 100% packet loss
+
+  The database container IP changed (it was restarted and got a new IP).
+  The hardcoded IP in DATABASE_URL is stale.
+
+  Task: Explain the Docker debugging toolkit. Write: how to use docker
+  logs (with --follow, --since, --tail), docker inspect for container
+  metadata, docker exec for interactive debugging, docker stats for
+  resource monitoring, docker events for real-time lifecycle events,
+  and the systematic approach to diagnosing container issues.
+
+assertions:
+  - type: llm_judge
+    criteria: "Docker logs usage is comprehensive — docker logs <container> shows stdout/stderr, --follow (-f) streams in real-time, --since '10m' shows last 10 minutes, --tail 100 shows last 100 lines, --timestamps adds timestamps. For containers that write logs to files instead of stdout, logs command shows nothing — must exec into container or mount log volume"
+    weight: 0.35
+    description: "Docker logs"
+  - type: llm_judge
+    criteria: "Docker inspect and exec are explained — docker inspect returns full JSON metadata (network settings, env vars, mounts, state, config). Use --format with Go templates to extract specific fields. docker exec -it <container> sh opens interactive shell for debugging (check files, environment, network). docker exec can also run one-off commands: docker exec api env, docker exec api cat /etc/hosts"
+    weight: 0.35
+    description: "Inspect and exec"
+  - type: llm_judge
+    criteria: "Systematic debugging approach is shown — (1) docker ps to check container status, (2) docker logs for application errors, (3) docker inspect for configuration and network info, (4) docker exec to investigate inside the container, (5) docker stats for resource usage. The IP issue demonstrates why you should use container names or Docker DNS instead of hardcoded IPs. Use Docker networks for reliable service discovery"
+    weight: 0.30
+    description: "Systematic approach"

package/courses/docker-container-debugging/scenarios/level-1/dockerfile-build-failures.yaml

@@ -0,0 +1,71 @@
+meta:
+  id: dockerfile-build-failures
+  level: 1
+  course: docker-container-debugging
+  type: output
+  description: "Debug Dockerfile build failures — diagnose COPY errors, missing dependencies, and common Dockerfile mistakes"
+  tags: [Docker, Dockerfile, build, COPY, dependencies, beginner]
+
+state: {}
+
+trigger: |
+  Your Docker build keeps failing with different errors:
+
+  $ docker build -t myapp .
+
+  Attempt 1:
+  Step 5/10: COPY package.json ./
+  COPY failed: file not found in build context or excluded by .dockerignore
+
+  The file exists in the project but the build context is wrong. You're
+  running docker build from the wrong directory, or .dockerignore is
+  excluding package.json.
+
+  After fixing the context:
+
+  Attempt 2:
+  Step 7/10: RUN npm install
+  npm ERR! code ENOENT
+  npm ERR! syscall open
+  npm ERR! path /app/package.json
+  npm ERR! No such file or directory
+
+  COPY succeeded but the WORKDIR wasn't set — files were copied to /
+  but npm install runs in /app.
+
+  After adding WORKDIR /app:
+
+  Attempt 3:
+  Step 8/10: RUN npm run build
+  sh: 1: node: not found
+
+  The base image doesn't have Node.js. The Dockerfile uses FROM ubuntu
+  instead of FROM node:20.
+
+  The problematic Dockerfile:
+  FROM ubuntu:22.04
+  RUN apt-get update
+  COPY . .
+  RUN npm install
+  RUN npm run build
+  CMD ["node", "dist/server.js"]
+
+  Task: Explain common Dockerfile build failures. Write: how the build
+  context works (what files are available during build), the role of
+  .dockerignore, common COPY/ADD errors, the importance of WORKDIR,
+  choosing the right base image, the order of Dockerfile instructions
+  for layer caching, and how to debug build failures step by step.
+
+assertions:
+  - type: llm_judge
+    criteria: "Build context is explained — the build context is the directory sent to the Docker daemon (specified in docker build <path>). COPY and ADD can only access files in the build context. .dockerignore excludes files from the context (like .gitignore). Common mistakes: running docker build from wrong directory, .dockerignore excluding needed files, trying to COPY files outside the build context (../file is not allowed)"
+    weight: 0.35
+    description: "Build context explained"
+  - type: llm_judge
+    criteria: "Common Dockerfile mistakes are covered — missing WORKDIR (files end up in /), wrong base image (missing runtime), COPY before dependency install (breaks layer caching — COPY package.json first, then npm install, then COPY . .), missing RUN apt-get install for dependencies, using ADD when COPY suffices (ADD does tar extraction and URL fetching), not cleaning up apt cache (bloats image)"
+    weight: 0.35
+    description: "Common mistakes"
+  - type: llm_judge
+    criteria: "Debugging approach is practical — read error messages carefully (they indicate the step that failed), use docker build --progress=plain for detailed output, inspect intermediate layers (build with --target or use BuildKit debug), check .dockerignore contents, verify build context with docker build --file and --context flags, use RUN ls to verify file locations during debugging"
+    weight: 0.30
+    description: "Debugging approach"

package/courses/docker-container-debugging/scenarios/level-1/environment-variable-issues.yaml

@@ -0,0 +1,74 @@
+meta:
+  id: environment-variable-issues
+  level: 1
+  course: docker-container-debugging
+  type: output
+  description: "Debug Docker environment variable issues — diagnose missing, overridden, or incorrectly passed env vars in containers"
+  tags: [Docker, environment-variables, ENV, env-file, configuration, beginner]
+
+state: {}
+
+trigger: |
+  Your containerized app is failing because of environment variable
+  issues:
+
+  $ docker run -d --name api \
+    -e DATABASE_URL=postgres://user:pass@db:5432/mydb \
+    -e API_KEY=sk-abc123 \
+    myapp:v1.0
+
+  $ docker logs api
+  Error: Missing required environment variable: API_SECRET
+  Error: DATABASE_URL has invalid format
+
+  Two issues:
+  1. API_SECRET isn't set — only API_KEY was provided, but the app
+     expects API_SECRET
+  2. DATABASE_URL value contains special characters in the password
+     that weren't properly quoted
+
+  $ docker exec api env | sort
+  API_KEY=sk-abc123
+  DATABASE_URL=postgres://user:pass@db:5432/mydb
+  HOME=/root
+  NODE_ENV=production
+  PATH=/usr/local/bin:/usr/bin:/bin
+
+  Wait — NODE_ENV=production is set even though you didn't specify it.
+  It must be set in the Dockerfile with ENV:
+
+  Dockerfile:
+  FROM node:20
+  ENV NODE_ENV=production
+  WORKDIR /app
+  COPY . .
+  RUN npm install --production
+  CMD ["node", "server.js"]
+
+  Ways to pass environment variables:
+  1. -e KEY=VALUE (single variable)
+  2. --env-file .env (file with KEY=VALUE lines)
+  3. ENV in Dockerfile (baked into image)
+  4. Docker Compose environment: section
+
+  Priority: runtime (-e) overrides Dockerfile (ENV).
+
+  Task: Explain Docker environment variables. Write: the different ways
+  to pass env vars (-e, --env-file, ENV, Compose), precedence rules,
+  how to inspect env vars in running containers, common mistakes (special
+  characters, missing quotes, wrong variable names), security concerns
+  (env vars visible in docker inspect), and best practices.
+
+assertions:
+  - type: llm_judge
+    criteria: "Env var methods are explained — -e KEY=VALUE at runtime, --env-file reads from file (one KEY=VALUE per line, no quotes needed), ENV in Dockerfile (baked into image, visible in all containers), Docker Compose environment section. Runtime values override Dockerfile ENV. ARG is build-time only and NOT available at runtime (common confusion)"
+    weight: 0.35
+    description: "Env var methods"
+  - type: llm_judge
+    criteria: "Common mistakes are covered — special characters in values need proper quoting (-e 'DB_URL=postgres://user:p@ss@db:5432/db'), missing variables (app expects different name), env var not available at runtime (used ARG instead of ENV), --env-file doesn't support comments inline with values in some versions, .env file not found (wrong path). Debugging: docker exec <container> env to see actual variables"
+    weight: 0.35
+    description: "Common mistakes"
+  - type: llm_judge
+    criteria: "Security concerns are addressed — env vars are visible in docker inspect output (anyone with Docker access can see them), they appear in /proc/<pid>/environ inside the container, they may be logged accidentally. Better alternatives for secrets: Docker secrets (Swarm), mount secret files as volumes, use secret management tools (Vault, AWS Secrets Manager). Never put secrets in Dockerfiles (they're baked into image layers)"
+    weight: 0.30
+    description: "Security concerns"

package/courses/docker-container-debugging/scenarios/level-1/first-debugging-shift.yaml

@@ -0,0 +1,70 @@
+meta:
+  id: first-debugging-shift
+  level: 1
+  course: docker-container-debugging
+  type: output
+  description: "Combined debugging shift — diagnose multiple Docker container failures using the full beginner debugging toolkit"
+  tags: [Docker, troubleshooting, combined, shift-simulation, beginner]
+
+state: {}
+
+trigger: |
+  You're helping a teammate deploy a 3-container application stack for
+  the first time. Nothing is working:
+
+  $ docker ps -a
+  CONTAINER ID   IMAGE            STATUS                     PORTS    NAMES
+  a1b2c3d4e5f6   myapp:v1         Exited (127) 2 min ago              api
+  b2c3d4e5f6g7   postgres:16      Up 5 minutes                        db
+  c3d4e5f6g7h8   redis:7          Exited (1) 3 min ago                cache
+
+  Three containers, two are stopped, one is running but inaccessible.
+
+  Issue 1 — api container (exit code 127):
+  $ docker logs api
+  /bin/sh: 1: node: not found
+  The Dockerfile uses FROM python:3.12 but CMD ["node", "server.js"].
+  Wrong base image!
+
+  Issue 2 — cache container (exit code 1):
+  $ docker logs cache
+  Fatal error: Can't open config file /etc/redis/redis.conf
+  A bind mount -v ./redis.conf:/etc/redis/redis.conf was specified
+  but ./redis.conf doesn't exist on the host. Docker created an empty
+  directory in its place.
+
+  Issue 3 — db container (running but inaccessible):
+  $ docker exec api ping db
+  (api is stopped, can't exec into it)
+
+  $ docker run --rm postgres:16 pg_isready -h db
+  db:5432 - no response
+
+  The database is running but on the default bridge network. The
+  hostname "db" doesn't resolve because default bridge doesn't
+  support DNS.
+
+  Additional issue found:
+  $ curl http://localhost:3000
+  Connection refused
+  No -p flag was used for the api container — no port published.
+
+  Task: Walk through debugging all three issues. Write: the triage
+  approach (check status, check logs, check configuration), the fix
+  for each issue, why exit code 127 means command not found, why Docker
+  creates directories for missing bind mount files, and the checklist
+  for running multi-container applications.
+
+assertions:
+  - type: llm_judge
+    criteria: "All three issues are correctly diagnosed — (1) exit code 127 = command not found, wrong base image (python instead of node), (2) bind mount of non-existent file creates empty directory (Docker's default behavior), redis can't read a directory as config file, (3) default bridge network doesn't support DNS resolution, containers can't find each other by name, also no port published for external access"
+    weight: 0.35
+    description: "All issues diagnosed"
+  - type: llm_judge
+    criteria: "Fixes are practical — (1) change Dockerfile base image to node:20 or fix CMD to use python, (2) ensure redis.conf exists before starting container, or use default redis config without the mount, (3) create custom network and put all containers on it, add -p flag for external access. Show the corrected docker run commands for each container"
+    weight: 0.35
+    description: "Practical fixes"
+  - type: llm_judge
+    criteria: "Multi-container checklist is provided — before starting: verify all images are correct and available, check all mount source paths exist, create a custom network, plan port mappings. Use Docker Compose for multi-container apps (avoids manual docker run flags). Debugging order: check status → check logs → check inspect → check network → fix and retry"
+    weight: 0.30
+    description: "Multi-container checklist"

package/courses/docker-container-debugging/scenarios/level-1/image-pull-failures.yaml

@@ -0,0 +1,68 @@
+meta:
+  id: image-pull-failures
+  level: 1
+  course: docker-container-debugging
+  type: output
+  description: "Debug Docker image pull failures — diagnose authentication errors, rate limits, and wrong image references"
+  tags: [Docker, image-pull, registry, authentication, Docker-Hub, beginner]
+
+state: {}
+
+trigger: |
+  You can't pull or run Docker images and see different error messages:
+
+  Scenario 1 — Image not found:
+  $ docker pull mycompany/backend:v2.1.0
+  Error response from daemon: pull access denied for mycompany/backend,
+  repository does not exist or may require 'docker login'
+
+  Is the image name wrong? Is it a private repository?
+  The image is on a private registry (ghcr.io), not Docker Hub:
+  $ docker pull ghcr.io/mycompany/backend:v2.1.0
+
+  Scenario 2 — Authentication required:
+  $ docker pull ghcr.io/mycompany/backend:v2.1.0
+  Error response from daemon: Head "https://ghcr.io/v2/mycompany/backend/
+  manifests/v2.1.0": unauthorized: authentication required
+
+  $ docker login ghcr.io -u myuser
+  Login Succeeded
+
+  $ docker pull ghcr.io/mycompany/backend:v2.1.0
+  v2.1.0: Pulling from mycompany/backend
+
+  Scenario 3 — Docker Hub rate limit:
+  $ docker pull nginx:latest
+  Error response from daemon: toomanyrequests: You have reached your
+  pull rate limit. You may increase the limit by authenticating.
+
+  Docker Hub limits anonymous pulls to 100/6h and authenticated to
+  200/6h. In CI/CD, this gets exhausted fast.
+
+  Scenario 4 — Platform mismatch:
+  $ docker pull myimage:latest
+  WARNING: image with reference myimage:latest was found but does not
+  match the specified platform (linux/arm64)
+
+  You're on an Apple Silicon Mac (ARM) but the image is only built
+  for linux/amd64. The container will run via emulation (slow) or fail.
+
+  Task: Explain Docker image pull issues. Write: how Docker resolves
+  image references (registry/repository:tag), authentication (docker
+  login, credential stores), Docker Hub rate limits and workarounds,
+  image tags vs digests, multi-platform images, and how to verify an
+  image exists before pulling.
+
+assertions:
+  - type: llm_judge
+    criteria: "Image reference format is explained — full format: registry/repository:tag. If no registry specified, Docker Hub is assumed. If no tag, :latest is assumed. Private registries require full URL (ghcr.io/org/image:tag, registry.company.com/image:tag). Common mistake: forgetting the registry prefix for non-Docker Hub images"
+    weight: 0.35
+    description: "Image references"
+  - type: llm_judge
+    criteria: "Authentication and rate limits are covered — docker login stores credentials in ~/.docker/config.json (can use credential helpers for security). Docker Hub rate limits: 100 pulls/6h anonymous, 200/6h authenticated. Workarounds: authenticate in CI/CD, use a pull-through cache or mirror, use private registry. For GHCR/ECR/GCR, use specific login commands or credential helpers"
+    weight: 0.35
+    description: "Auth and rate limits"
+  - type: llm_judge
+    criteria: "Tags, digests, and platforms are explained — tags are mutable (latest can change), digests are immutable (sha256:abc...). Use digests for reproducible builds. Multi-platform images: docker manifest inspect shows supported platforms. --platform flag to pull specific architecture. Apple Silicon users: some images aren't built for arm64, causing emulation overhead or failures"
+    weight: 0.30
+    description: "Tags and platforms"

package/courses/docker-container-debugging/scenarios/level-1/port-mapping-issues.yaml

@@ -0,0 +1,67 @@
+meta:
+  id: port-mapping-issues
+  level: 1
+  course: docker-container-debugging
+  type: output
+  description: "Debug Docker port mapping issues — diagnose why you can't connect to a containerized service"
+  tags: [Docker, port-mapping, networking, EXPOSE, publish, beginner]
+
+state: {}
+
+trigger: |
+  You started your web application container but can't reach it:
+
+  $ docker run -d --name webapp myapp:latest
+  $ curl http://localhost:3000
+  curl: (7) Failed to connect to localhost port 3000: Connection refused
+
+  The Dockerfile has EXPOSE 3000, so why isn't it accessible?
+
+  $ docker ps
+  CONTAINER ID   IMAGE         STATUS       PORTS     NAMES
+  a1b2c3d4e5f6   myapp:latest  Up 1 min               webapp
+
+  The PORTS column is empty! EXPOSE in the Dockerfile is just
+  documentation — it doesn't actually publish the port. You need -p:
+
+  $ docker run -d --name webapp -p 3000:3000 myapp:latest
+
+  Now another issue:
+  $ curl http://localhost:3000
+  curl: (7) Failed to connect to localhost port 3000: Connection refused
+
+  $ docker logs webapp
+  Server listening on 127.0.0.1:3000
+
+  The app is listening on 127.0.0.1 (localhost inside the container),
+  not 0.0.0.0. Inside the container, 127.0.0.1 means the container's
+  own loopback — it's not accessible from outside the container.
+
+  Fix: configure the app to listen on 0.0.0.0:3000.
+
+  After fixing:
+  $ docker run -d --name webapp -p 8080:3000 myapp:latest
+  $ curl http://localhost:8080
+  {"status": "ok"}
+
+  Port mapping: host port 8080 → container port 3000.
+
+  Task: Explain Docker port mapping. Write: the difference between
+  EXPOSE and -p/--publish, how port mapping works (host:container),
+  why apps must listen on 0.0.0.0 not 127.0.0.1, the -P flag for
+  random ports, binding to specific interfaces (-p 127.0.0.1:8080:3000),
+  and common port mapping mistakes.
+
+assertions:
+  - type: llm_judge
+    criteria: "EXPOSE vs -p is clearly explained — EXPOSE is metadata/documentation in the Dockerfile, it does NOT actually publish the port. -p (--publish) creates the actual port mapping at runtime. Format: -p <host-port>:<container-port>. -P (capital P) publishes all EXPOSE'd ports to random host ports. You can run containers without EXPOSE and still use -p"
+    weight: 0.35
+    description: "EXPOSE vs publish"
+  - type: llm_judge
+    criteria: "The 0.0.0.0 vs 127.0.0.1 issue is explained — containers have their own network namespace. 127.0.0.1 inside a container is the container's loopback, not the host's. Apps must bind to 0.0.0.0 (all interfaces) to be accessible from outside the container. This is the most common port mapping debugging issue. Some frameworks default to 127.0.0.1 (Rails, Flask) and need explicit configuration"
+    weight: 0.35
+    description: "Bind address explained"
+  - type: llm_judge
+    criteria: "Port mapping variations and mistakes are covered — -p 8080:3000 (host 8080 → container 3000), -p 127.0.0.1:8080:3000 (only accessible from host localhost), -p 3000 (random host port → container 3000). Common mistakes: forgetting -p entirely, app binding to wrong address, port already in use on host (docker: bind: address already in use), confusing host and container ports"
+    weight: 0.30
+    description: "Variations and mistakes"

package/courses/docker-container-debugging/scenarios/level-1/resource-limits-oom.yaml

@@ -0,0 +1,70 @@
+meta:
+  id: resource-limits-oom
+  level: 1
+  course: docker-container-debugging
+  type: output
+  description: "Debug Docker resource limits and OOM kills — understand memory limits, CPU constraints, and why containers get killed"
+  tags: [Docker, resource-limits, OOM, memory, CPU, cgroups, beginner]
+
+state: {}
+
+trigger: |
+  Your container keeps getting killed mysteriously:
+
+  $ docker run -d --name worker --memory=256m worker-app:v1.0
+  $ docker ps
+  CONTAINER ID   IMAGE             STATUS                     NAMES
+  a1b2c3d4e5f6   worker-app:v1.0   Exited (137) 2 mins ago   worker
+
+  Exit code 137 again — was it OOM killed?
+
+  $ docker inspect worker --format='{{.State.OOMKilled}}'
+  true
+
+  $ docker stats --no-stream worker
+  (container is stopped, can't get stats)
+
+  Before the kill, memory usage was climbing:
+  $ docker run -d --name worker --memory=256m worker-app:v1.0
+  $ docker stats worker --no-stream
+  CONTAINER   CPU %   MEM USAGE / LIMIT   MEM %
+  worker      45%     248MiB / 256MiB     96.88%
+
+  The container is using 248MiB of its 256MiB limit — about to be killed.
+
+  Understanding the limits:
+  --memory=256m sets a hard limit (cgroup). If the process tries to
+  allocate more, the kernel's OOM killer terminates it (SIGKILL = 137).
+
+  --memory-reservation=128m sets a soft limit (scheduling hint, not
+  enforced). --memory-swap=512m sets swap limit (defaults to 2x memory).
+
+  For CPU:
+  --cpus=0.5 limits to 50% of one CPU core
+  --cpu-shares=512 sets relative weight (default 1024)
+
+  $ docker run -d --name worker \
+    --memory=512m \
+    --memory-reservation=256m \
+    --cpus=1.0 \
+    worker-app:v1.0
+
+  Task: Explain Docker resource limits. Write: how memory limits work
+  (cgroups hard limit, OOM kill behavior), how CPU limits work (cpus
+  vs cpu-shares), the difference between --memory and --memory-reservation,
+  how to monitor resource usage (docker stats), how to right-size
+  container limits, and what happens when limits are too low or not set.
+
+assertions:
+  - type: llm_judge
+    criteria: "Memory limits are explained — --memory sets hard cgroup limit, kernel OOM killer sends SIGKILL (exit code 137) when exceeded. --memory-reservation is a soft limit (best effort, not enforced). --memory-swap controls total memory + swap (default 2x memory, set to -1 for unlimited swap, set equal to --memory to disable swap). OOMKilled flag in docker inspect confirms OOM"
+    weight: 0.35
+    description: "Memory limits"
+  - type: llm_judge
+    criteria: "CPU limits are explained — --cpus=N limits to N CPU cores (fractional allowed, e.g., 0.5), --cpu-shares sets relative weight in contention (default 1024, only matters when CPU is contested), --cpuset-cpus pins to specific cores. Without limits, containers compete for all host resources — one container can starve others"
+    weight: 0.35
+    description: "CPU limits"
+  - type: llm_judge
+    criteria: "Monitoring and right-sizing are practical — docker stats shows real-time CPU, memory, network, disk I/O per container. docker stats --no-stream for one-time snapshot. Right-sizing: run without limits, observe actual usage over time, set memory limit to peak usage + 25% buffer, set CPU based on typical load. Without limits: containers can use all host memory/CPU, causing host instability"
+    weight: 0.30
+    description: "Monitoring and sizing"

package/courses/docker-container-debugging/scenarios/level-1/volume-mount-problems.yaml

@@ -0,0 +1,66 @@
+meta:
+  id: volume-mount-problems
+  level: 1
+  course: docker-container-debugging
+  type: output
+  description: "Debug Docker volume mount problems — diagnose permission errors, empty directories, and data persistence issues"
+  tags: [Docker, volumes, bind-mounts, permissions, storage, beginner]
+
+state: {}
+
+trigger: |
+  You're trying to persist data from your container but running into
+  mount issues:
+
+  Scenario 1 — Empty directory after mount:
+  $ docker run -d -v /data/db:/var/lib/postgresql/data postgres:16
+  $ docker exec -it <container> ls /var/lib/postgresql/data
+  (empty!)
+
+  The host directory /data/db didn't exist before the mount. Docker
+  created it (as root) but it's empty. PostgreSQL expected to find
+  its data files there or initialize in a writable directory.
+
+  Scenario 2 — Permission denied:
+  $ docker run -d -v $(pwd)/app:/app --user 1000:1000 node:20
+  $ docker logs <container>
+  Error: EACCES: permission denied, mkdir '/app/node_modules'
+
+  The container runs as user 1000 but the mounted directory is owned
+  by root. The user can't write to the mount.
+
+  Scenario 3 — Data disappears:
+  $ docker run --name mydb postgres:16
+  # Insert some data...
+  $ docker rm mydb
+  $ docker run --name mydb postgres:16
+  # Data is gone!
+
+  No volume was specified — data was stored in the container's writable
+  layer, which is deleted when the container is removed.
+
+  Types of Docker storage:
+  1. Bind mount: -v /host/path:/container/path (maps host directory)
+  2. Named volume: -v myvolume:/container/path (Docker-managed)
+  3. tmpfs: --tmpfs /container/path (in-memory, not persisted)
+  4. Container layer: default writable layer (deleted with container)
+
+  Task: Explain Docker storage and how to debug volume issues. Write:
+  the difference between bind mounts, named volumes, and tmpfs, common
+  permission problems and how to fix them, why data disappears without
+  volumes, how to inspect volumes (docker volume inspect), and best
+  practices for data persistence.
+
+assertions:
+  - type: llm_judge
+    criteria: "Storage types are explained — bind mounts map host directory to container (host path must exist, performance depends on host OS), named volumes are Docker-managed (stored in /var/lib/docker/volumes, portable, Docker manages permissions), tmpfs is in-memory (fast, not persisted, good for secrets). Container writable layer is the default (copy-on-write, deleted when container is removed)"
+    weight: 0.35
+    description: "Storage types"
+  - type: llm_judge
+    criteria: "Permission issues are addressed — bind mounts: host directory UID/GID must match container user, use --user to match, or chown in Dockerfile. Named volumes: Docker creates with correct permissions for the container. Common fix: run as root temporarily to fix permissions, or use init scripts. On macOS/Windows with Docker Desktop, bind mount performance is slower due to file system translation"
+    weight: 0.35
+    description: "Permission issues"
+  - type: llm_judge
+    criteria: "Debugging and best practices are practical — docker volume ls to list volumes, docker volume inspect to see mount point, docker inspect <container> to see mount configuration. Use docker volume prune to clean unused volumes (careful!). Best practices: use named volumes for databases (not bind mounts), use bind mounts for development (live code reload), never store important data in the container layer, backup volumes regularly"
+    weight: 0.30
+    description: "Debugging and practices"

package/courses/docker-container-debugging/scenarios/level-2/container-health-checks.yaml

@@ -0,0 +1,73 @@
+meta:
+  id: container-health-checks
+  level: 2
+  course: docker-container-debugging
+  type: output
+  description: "Debug Docker health check issues — diagnose failing health checks, configure timing parameters, and design effective health endpoints"
+  tags: [Docker, health-checks, HEALTHCHECK, monitoring, reliability, intermediate]
+
+state: {}
+
+trigger: |
+  Your container keeps showing as "unhealthy" even though the
+  application works fine:
+
+  $ docker ps
+  CONTAINER ID   IMAGE     STATUS                   PORTS
+  a1b2c3d4e5f6   myapp     Up 5m (unhealthy)        8080/tcp
+
+  $ docker inspect myapp --format='{{json .State.Health}}' | jq
+  {
+    "Status": "unhealthy",
+    "FailingStreak": 5,
+    "Log": [
+      {
+        "Start": "2025-12-01T10:05:00Z",
+        "End": "2025-12-01T10:05:10Z",
+        "ExitCode": 1,
+        "Output": "  % Total    % Received\n  OCI runtime exec failed: exec failed: unable to start container process: exec: \"curl\": executable file not found in $PATH"
+      }
+    ]
+  }
+
+  The health check uses curl but the image doesn't have curl installed!
+
+  Dockerfile:
+  FROM node:20-alpine
+  HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
+    CMD curl -f http://localhost:3000/health || exit 1
+  ...
+
+  Alpine doesn't include curl. Options:
+  1. Install curl: RUN apk add --no-cache curl
+  2. Use wget (included in alpine): CMD wget -q -O- http://localhost:3000/health
+  3. Use Node.js: CMD node -e "require('http').get('http://localhost:3000/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"
+
+  After fixing, a second issue: the app takes 45 seconds to start but
+  the health check starts immediately with retries=3 and interval=30s.
+  After 90s (3 × 30s), it's marked unhealthy during startup.
+
+  Fix: Add start_period:
+  HEALTHCHECK --interval=10s --timeout=5s --start-period=60s --retries=3 \
+    CMD wget -q -O- http://localhost:3000/health || exit 1
+
+  Task: Explain Docker health checks in depth. Write: the HEALTHCHECK
+  instruction parameters (interval, timeout, retries, start-period,
+  start-interval), health check states (starting, healthy, unhealthy),
+  common health check failures (missing tools, wrong endpoint, timing),
+  how to design good health check endpoints, and health check debugging
+  with docker inspect.
+
+assertions:
+  - type: llm_judge
+    criteria: "HEALTHCHECK parameters are explained — interval: time between checks (default 30s), timeout: max time for check to complete (default 30s), retries: consecutive failures before unhealthy (default 3), start-period: grace period where failures don't count (default 0s), start-interval: check frequency during start-period (default 5s, Docker 25+). Total startup tolerance = start-period + (retries × interval)"
+    weight: 0.35
+    description: "HEALTHCHECK parameters"
+  - type: llm_judge
+    criteria: "Common failures are diagnosed — missing tools in image (curl/wget not installed), health endpoint returns error (wrong port, path, or status code), timing issues (app starts slowly, health check fails during startup), health check command syntax error (shell vs exec form), wrong process checked (health check hits sidecar not main app). Debug with docker inspect --format='{{json .State.Health}}'"
+    weight: 0.35
+    description: "Common failures"
+  - type: llm_judge
+    criteria: "Health endpoint design is covered — good health check: checks that the process can handle requests (not just that it's running), checks critical dependencies (database connection, cache), responds quickly (< 1 second), returns appropriate HTTP status code. Bad health check: checks that are too expensive (full database query), checks external services (makes health dependent on others), no timeout"
+    weight: 0.30
+    description: "Health endpoint design"