docker_for_agents v1.0.0

name: "docker_for_agents" description: "Write Dockerfiles, build/run containers, and set up multi-service docker compose stacks. Triggers when containerizing an app, debugging container failures, or orchestrating local services."

Docker for Agents

Purpose

Go from an un-containerized app to a working Dockerfile and docker run command, or a multi-service compose.yaml, without guessing at syntax. Covers the instructions and flags that actually matter, layer-cache pitfalls, and the failure modes agents hit most.

Workflow

1. Check the daemon. docker info should return server details. If it fails with a connection error, the Docker daemon isn't running (or isn't installed) — report that and stop; nothing else below will work.

2. Write the Dockerfile. Start minimal; add only what's needed:

dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "app.py"]

• FROM — pinned base image (:3.12-slim, not :latest, so rebuilds don't drift).
• WORKDIR /app — sets the working directory for everything after it.
• COPY <host> <image> — copy files in. Copy dependency manifests first, then install, then copy code so a code edit doesn't bust the dependency layer cache.
• RUN — shell commands at build time (installs, compiles).
• CMD ["a", "b"] — the default process. Exec form (JSON array, no shell) is the default; CMD python app.py (shell form) runs via /bin/sh -c, which can break signal handling.
• .dockerignore (next to the Dockerfile) keeps build context small: venv/, .git/, __pycache__/, node_modules/, *.pyc.

3. Build and run.

bash
docker build -t myapp:0.1.0 .
docker run --rm -p 8000:8000 --name myapp myapp:0.1.0

Flags that matter:

• --rm — delete the container when it exits (default to this for one-off runs so dead containers don't pile up).
• -d — detached (background), for long-running services. -it — interactive TTY, for shells/debugging (docker run --rm -it myapp:0.1.0 bash). Pick one; they're for different jobs.
• -p 8000:8000 — publish host:container port. Without it, the container's port is unreachable from the host.
• -v ./data:/app/data — bind-mount a host path for dev or persistence; -v appdata:/app/data — named volume, data survives container removal.
• --env-file .env — load KEY=VALUE lines (comments with #); -e KEY=VAL for one-offs.
• --name — stable name so you can docker logs <name> / docker exec -it <name> bash.

4. Shrink with multi-stage builds when the final image only needs the built artifact:

dockerfile
FROM golang:1.23-alpine AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o server ./cmd/server

FROM alpine:3.20
WORKDIR /app
COPY --from=build /src/server .
CMD ["./server"]

Toolchain stays in the build stage; the runtime image only carries the binary.

5. Multi-service: docker compose. Compose v2 is a plugin — the command is docker compose (no hyphen); the legacy standalone docker-compose is end-of-life. Preferred filename is compose.yaml (docker-compose.yml still works). No version: field — it's deprecated.

yaml
services:
  api:
    build: .
    ports:
      - "8000:8000"
    env_file: .env
    depends_on:
      - db
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

docker compose up --build builds and starts everything; docker compose up -d runs detached; docker compose down stops and removes containers/network. Services reach each other by service name (db above → api connects to host db).

Output Contract

When asked to containerize something, deliver: a Dockerfile, a .dockerignore, and the exact docker build / docker run commands (or a compose.yaml plus the up/down commands). State the host:container port mapping and where data persists, if anywhere.

Operating Rules

1. Layer caching: copy manifests before code. COPY . . before RUN pip install means every edit reinstalls dependencies — slow and wasteful.
2. Port already in use: the daemon refuses the publish (bind: address already in use). Pick a free host port (-p 8001:8000) or stop the conflicting container.
3. Container exits immediately: the main process died or the CMD was wrong. Run docker logs <name> first; check the command actually exists in the image and, for servers, that it binds 0.0.0.0 (a server bound to 127.0.0.1 inside the container is unreachable).
4. Never --env-file a secrets file into an image build context carelessly: env at docker run stays out of the image; a secret copied in at build time is baked into the image layers forever.
5. One process per container as the default pattern; reach for compose when you need more than one service, not CMD a && b.
6. Commands above are verified from docs.docker.com (2026-09-17); Docker is not installed on this machine, so nothing here was executed locally — confirm against the target host's daemon before asserting behavior.