Docker

When to Use

User needs Docker expertise — from building images to production deployments. Agent handles Dockerfiles, compose orchestration, networking, security hardening, and troubleshooting.

Quick Reference

Topic	File
Dockerfile best practices	images.md
Docker Compose patterns	compose.md
Networking and volumes	infrastructure.md
Security hardening	security.md

Image Building Traps

• apt-get update and apt-get install in separate RUN layers = stale packages weeks later — always combine them
• python:latest today is different than python:latest tomorrow — pin versions like python:3.11.5-slim
• Multi-stage builds: forgotten --from=builder copies from wrong stage silently
• COPY before RUN invalidates cache on every file change — copy requirements first, install, then copy code

Runtime Crashes

• Default log driver has no size limit — one chatty container fills disk and crashes host
• OOM killer strikes without warning — set memory limits with -m 512m on every container
• Container runs as root by default — add USER nonroot or security scans fail and platforms reject
• localhost inside container is container's localhost, not host — bind to 0.0.0.0

Networking Traps

• Container DNS only works on custom networks — default bridge can't resolve container names
• Published ports bind to 0.0.0.0 by default — use 127.0.0.1:5432:5432 for local-only
• Zombie connections from killed containers — set proper health checks and restart policies
• Port already in use: previous container still stopping — wait or force remove

Compose Traps

• depends_on waits for container start, not service ready — use condition: service_healthy with healthcheck
• .env file in wrong directory silently ignored — must be next to docker-compose.yml
• Volume mounts overwrite container files — empty host dir = empty container dir
• YAML anchors don't work across files — extends deprecated, use multiple compose files

Volumes and Data

• Anonymous volumes from Dockerfile VOLUME instruction accumulate silently — use named volumes
• Bind mounts have host permission issues — container user must match host user or use :z suffix
• docker system prune doesn't remove named volumes — add -volumes flag explicitly
• Stopped container data persists until container removed — docker rm deletes data

Resource Leaks

• Dangling images grow unbounded — docker image prune regularly
• Build cache grows forever — docker builder prune reclaims space
• Stopped containers consume disk — docker container prune or --rm on run
• Networks pile up from compose projects — docker network prune

Secrets and Security

• ENV and COPY bake secrets into layer history permanently — use secrets mount or runtime env
• --privileged disables all security — almost never needed, find specific capability instead
• Images from unknown registries may be malicious — verify sources
• Build args visible in image history — don't use for secrets

Debugging

• Exit code 137 = OOM killed, 139 = segfault — check docker inspect --format='{{.State.ExitCode}}'
• Container won't start: check logs even for failed containers — docker logs <container>
• No shell in distroless images — docker cp files out or use debug sidecar
• Inspect filesystem of dead container — docker cp deadcontainer:/path ./local