Docker
Overview
Docker packages applications into isolated containers that run consistently across environments. A Dockerfile defines the image build steps, Compose orchestrates multi-container services, and production patterns ensure small, secure, performant images.
When to use: Containerizing applications, creating reproducible dev environments, orchestrating multi-service stacks, deploying to container platforms (ECS, Kubernetes, Fly.io, Railway, Coolify).
When NOT to use: Simple static sites with no backend (use CDN deploy), single-binary CLI tools (distribute the binary), or when the target platform has native buildpacks (Heroku, Vercel) and you don't need container control.
Quick Reference
| Pattern | Approach | Key Points |
|---|---|---|
| Multi-stage build | Separate builder and production stages | 80%+ image size reduction, no dev deps in production |
| Layer caching | Copy lockfile first, install, then copy source | Dependency layer cached across builds |
| Non-root user | RUN adduser + USER in final stage | Never run production containers as root |
| Health check | HEALTHCHECK CMD curl or node/python check | Enables orchestrator restart on failure |
.dockerignore | Exclude node_modules, .git, .env | Smaller build context, faster builds |
| Compose services | compose.yaml with service definitions | Dev environment in one command |
| Compose override | compose.prod.yaml with production settings | Environment-specific config without duplication |
| Named volumes | volumes: in Compose for persistent data | Survives container recreation |
| Build cache mount | RUN --mount=type=cache,target=/root/.npm | Persistent cache across builds |
| Secrets in build | RUN --mount=type=secret,id=token | Never bake secrets into image layers |
| Image pinning | Pin to major.minor or digest | Reproducible builds, avoid surprise breakage |
| Container networking | Custom bridge networks with service discovery | Containers resolve each other by service name |
| Compose watch | develop.watch with sync/rebuild actions | Live reload without volume mounts |
| Init process | --init flag or tini entrypoint | Proper signal handling and zombie reaping |
| Multi-platform | docker buildx build --platform | ARM (Apple Silicon, Graviton) + x86 in one image |
| Monorepo prune | turbo prune app --docker | Minimal build context from workspace dependencies |
| CI layer caching | cache-from/cache-to with GHA or registry | Avoid full rebuilds in CI pipelines |
| Debug containers | docker exec, docker logs, dive | Inspect running containers and image layers |
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
| Installing dev dependencies in production image | Multi-stage build: install in builder, copy artifacts to runtime |
| Copying source before installing dependencies | Copy lockfile first, npm ci, then copy source for cache reuse |
| Running as root in production | Create non-root user, USER directive in final stage |
| Hardcoding secrets in Dockerfile or ENV | Use build secrets (--mount=type=secret) or runtime env |
Using latest tag for base images | Pin to specific version (node:24-alpine) |
No .dockerignore file | Exclude node_modules, .git, .env, build artifacts |
Using npm install instead of npm ci | npm ci for deterministic, lockfile-based installs |
| HEALTHCHECK missing | Add health check for orchestrator integration |
Large base images (node:24) | Use alpine variants (node:24-alpine) for smaller images |
Ignoring .env file precedence in Compose | environment: in Compose overrides .env file values |
| Building entire monorepo for one service | Use turbo prune --docker for minimal build context |
| No layer caching in CI | Use cache-from/cache-to with GHA or registry backend |
| Building only for x86 when deploying to ARM | Use docker buildx with --platform linux/amd64,linux/arm64 |
Delegation
- Dockerfile review: Use
Taskagent to audit Dockerfiles for size, security, and caching - Compose exploration: Use
Exploreagent to discover existing Docker configurations - Architecture decisions: Use
Planagent for container orchestration strategy
If the
ci-cd-architectureskill is available, delegate CI/CD pipeline and deployment strategy to it. If theapplication-securityskill is available, delegate container security scanning and hardening review to it.
References
- Dockerfile patterns: multi-stage builds, layer caching, and image optimization
- Compose: services, networking, volumes, and environment management
- Security: non-root users, secrets, scanning, and production hardening
- Buildx: multi-platform builds for ARM and x86
- CI: GitHub Actions caching, registry push, and automated builds
- Monorepo: Turborepo prune, pnpm workspaces, and selective builds
- Debugging: logs, exec, inspect, layer analysis, and network troubleshooting