Use when working with Docker containers — debugging container failures, writing Dockerfiles, docker-compose for integration tests, image optimization, or deploying containerized applications
Use when working with Docker containers — debugging container failures, writing Dockerfiles, docker-compose for integration tests, image optimization, or deploying containerized applications
Docker Mastery
Overview
Docker is a platform for building, shipping, and running applications, not just isolation.
Agents should think in containers: reproducible environments, declarative dependencies, isolated execution.
Core principle: Containers are not virtual machines. They share the kernel but isolate processes, filesystems, and networks.
Violating the letter of these guidelines is violating the spirit of containerization.
The Iron Law
UNDERSTAND THE CONTAINER BEFORE DEBUGGING INSIDE IT
Before exec'ing into a container or adding debug commands:
Check the image (what's installed?)
Check mounts (what host files are visible?)
Check environment variables (what config is passed?)
Check the Dockerfile (how was it built?)
Random debugging inside containers wastes time. Context first, then debug.
Sandbox debugging - Issues with Hive's Docker sandbox mode
Use this ESPECIALLY when:
Tests pass locally but fail in CI (environment mismatch)
"Works on my machine" problems
Need to test against specific dependency versions
Multiple services must coordinate (database + API)
Building for production deployment
Core Concepts
Images vs Containers
Image: Read-only template (built from Dockerfile)
Container: Running instance of an image (ephemeral by default)
# Build once
docker build -t myapp:latest .
# Run many times
docker run --rm myapp:latest
docker run --rm -e DEBUG=true myapp:latest
Key insight: Changes inside containers are lost unless committed or volumes are used.
Volumes & Mounts
Mount host directories into containers for persistence and code sharing:
# Mount current directory to /app in container
docker run -v $(pwd):/app myapp:latest
# Project directory is mounted automatically# Your code edits (via Read/Write/Edit tools) affect the host# Container sees the same files at runtime
How maestro uses this: Project directory is mounted into container, so file tools work on host, bash commands run in container.
Multi-Stage Builds
Minimize image size by using multiple FROM statements:
# Build stage (large, has compilers)
FROM node:22 AS builder
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install
COPY . .
RUN bun run build
# Runtime stage (small, production only)
FROM node:22-slim
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]
Result: Builder tools (TypeScript, bundlers) not included in final image.
