docker-mastery

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:

1. Check the image (what's installed?)
2. Check mounts (what host files are visible?)
3. Check environment variables (what config is passed?)
4. Check the Dockerfile (how was it built?)

Random debugging inside containers wastes time. Context first, then debug.

When to Use

Use this skill when working with:

• Container build failures - Dockerfile errors, missing dependencies
• Test environment setup - Reproducible test environments across machines
• Integration test orchestration - Multi-service setups (DB + API + tests)
• Dockerfile authoring - Writing efficient, maintainable Dockerfiles
• Image size optimization - Reducing image size, layer caching
• Deployment - Containerized application deployment
• 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

# Hive worktrees are mounted automatically
# Your code edits (via Read/Write/editFiles tools) affect the host
# Container sees the same files at runtime

How Hive uses this: Worktree 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.

Docker Compose for Multi-Service Setups

Define multiple services in docker-compose.yml:

version: '3.8'
services:
  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: testpass
    ports:
      - "5432:5432"
  
  api:
    build: .
    environment:
      DATABASE_URL: postgres://db:5432/testdb
    depends_on:
      - db
    ports:
      - "3000:3000"

Run with: docker-compose up -d Teardown with: docker-compose down

Network Modes

• bridge (default): Isolated network, containers can talk to each other by name
• host: Container uses host's network directly (no isolation)
• none: No network access

When to use host mode: Debugging network issues, accessing host services directly.

Common Patterns

Debug a Failing Container

Problem: Container exits immediately, logs unclear.

Pattern:

1. Run interactively with shell:

   docker run -it --entrypoint sh myapp:latest
   

2. Inspect filesystem, check if dependencies exist:

   ls /app
   which node
   cat /etc/os-release
   

3. Run command manually to see full error:

   node dist/index.js
   

Integration Tests with Docker Compose

Pattern:

1. Define services in docker-compose.test.yml
2. Add wait logic (wait for DB to be ready)
3. Run tests
4. Teardown

# docker-compose.test.yml
services:
  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: test
  test:
    build: .
    command: bun run test:integration
    depends_on:
      - db
    environment:
      DATABASE_URL: postgres://postgres:test@db:5432/testdb

docker-compose -f docker-compose.test.yml up --abort-on-container-exit
docker-compose -f docker-compose.test.yml down

Optimize Dockerfile

Anti-pattern:

FROM node:22
WORKDIR /app
COPY . .              # Copies everything (including node_modules, .git)
RUN bun install       # Invalidates cache on any file change
CMD ["bun", "run", "start"]

Optimized:

FROM node:22-slim     # Use slim variant
WORKDIR /app

# Copy dependency files first (cache layer)
COPY package.json bun.lockb ./
RUN bun install --production

# Copy source code (changes frequently)
COPY src ./src
COPY tsconfig.json ./

CMD ["bun", "run", "start"]

Add .dockerignore:

node_modules
.git
.env
*.log
dist
.DS_Store

Handle Missing Dependencies

Problem: Command fails with "not found" in container.

Pattern:

1. Check if dependency is in image:

   docker run -it myapp:latest which git
   

2. If missing, add to Dockerfile:

   RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
   

3. Or use a richer base image (e.g., node:22 instead of node:22-slim).

Sandbox Integration

How Hive Wraps Commands

When sandbox mode is active (sandbox: 'docker' in config):

1. Hive hook intercepts bash commands before execution
2. Wraps with docker run --rm -v <worktree>:/workspace -w /workspace <image> sh -c "<command>"
3. Command runs in container, but file edits (read/editFiles) still affect the host

Workers are unaware — they issue normal bash commands, Hive handles containerization.

When Host Access is Needed

Some operations MUST run on host:

• Git operations (commit, push, branch) — repo state is on host
• Host-level tools (Docker itself, system config)
• Cross-worktree operations (accessing main repo from worktree)

Pattern: Use HOST: prefix to escape sandbox:

HOST: git status
HOST: docker ps

If you need host access frequently: Report as blocked and ask user if sandbox should be disabled for this task.

Persistent vs Ephemeral Containers

Current (v1.2.0): Each command runs docker run --rm (ephemeral). State does NOT persist.

Example: npm install lodash in one command → not available in next command.

Workaround: Install dependencies in Dockerfile, not at runtime.

Future: docker exec will reuse containers, persisting state across commands.

Auto-Detected Images

Hive detects runtime from project files:

• package.json → node:22-slim
• requirements.txt / pyproject.toml → python:3.12-slim
• go.mod → golang:1.22-slim
• Cargo.toml → rust:1.77-slim
• Dockerfile → Builds from project Dockerfile
• Fallback → ubuntu:24.04

Override: Set dockerImage in config (~/.config/opencode/agent_hive.json).

Red Flags - STOP

If you catch yourself:

• Installing packages on host instead of in Dockerfile
• Running docker build without .dockerignore (cache invalidation)
• Using latest tag in production (non-reproducible)
• Ignoring container exit codes (hides failures)
• Assuming state persists between docker run --rm commands
• Using absolute host paths in Dockerfile (not portable)
• Copying secrets into image layers (leaks credentials)

ALL of these mean: STOP. Review pattern.

Anti-Patterns

Excuse	Reality
"I'll just run it on host"	Container mismatch bugs are worse to debug later. Build happens in container anyway.
"Works in my container, don't need CI"	CI uses different cache state. Always test in CI-like environment.
"I'll optimize the Dockerfile later"	Later never comes. Large images slow down deployments now.
"latest tag is fine for dev"	Dev should match prod. Pin versions or face surprises.
"Don't need .dockerignore, COPY is fast"	Invalidates cache on every file change. Wastes minutes per build.
"Install at runtime, not in image"	Ephemeral containers lose state. Slows down every command.
"Skip depends_on, services start fast"	Race conditions in integration tests. Use wait-for-it or health checks.

Verification Before Completion

Before marking Docker work complete:

• Container runs successfully: docker run --rm <image> <command> exits 0
• Tests pass inside container (not just on host)
• No host pollution (dependencies installed in container, not host)
• .dockerignore exists if using COPY . .
• Image tags are pinned (not latest) for production
• Multi-stage build used if applicable (separate build/runtime)
• Integration tests teardown properly (docker-compose down)

If any fail: Don't claim success. Fix or report blocker.

Quick Reference

Task	Command Pattern
Debug container	docker run -it --entrypoint sh <image>
Run with mounts	docker run -v $(pwd):/app <image>
Multi-service tests	docker-compose up --abort-on-container-exit
Check image contents	docker run --rm <image> ls /app
Optimize build	Add .dockerignore, use multi-stage, pin versions
Escape Hive sandbox	Prefix with HOST: (e.g., HOST: git status)

Related Skills

• Refer to the skill at ../systematic-debugging/SKILL.md - When container behavior is unexpected
• Refer to the skill at ../test-driven-development/SKILL.md - Write tests that run in containers
• Refer to the skill at ../verification-before-completion/SKILL.md - Verify tests pass in container before claiming done