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

# 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.

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:
   bashCopy

   docker run -it --entrypoint sh myapp:latest
   

2. Inspect filesystem, check if dependencies exist:
   bashCopy

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

3. Run command manually to see full error:
   bashCopy

   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:
   bashCopy

   docker run -it myapp:latest which git
   

2. If missing, add to Dockerfile:
   dockerfileCopy

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

Hive 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 <project>:/workspace -w /workspace <image> sh -c "<command>"
3. Command runs in container, but file edits (Read/Write/Edit) still affect 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-project operations (accessing external repos or tools)

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

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

Related Skills

• maestro skill maestro:debugging - When container behavior is unexpected
• maestro skill maestro:tdd - Write tests that run in containers
• maestro skill maestro:verification - Verify tests pass in container before claiming done