docker

name	Docker
description	Run containers in production avoiding common crashes, security holes, and resource traps.
metadata	{"clawdbot":{"emoji":"🐳","requires":{"bins":["docker"]},"os":["linux","darwin","win32"]}}

Docker Gotchas

Image Building

• 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

• 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