SKILL.md
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](references/dockerfile-patterns.md)
- [Compose: services, networking, volumes, and environment management](references/compose.md)
- [Security: non-root users, secrets, scanning, and production hardening](references/security.md)
- [Buildx: multi-platform builds for ARM and x86](references/buildx-and-multiplatform.md)
- [CI: GitHub Actions caching, registry push, and automated builds](references/ci-caching.md)
- [Monorepo: Turborepo prune, pnpm workspaces, and selective builds](references/monorepo-builds.md)
- [Debugging: logs, exec, inspect, layer analysis, and network troubleshooting](references/debugging.md)