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
Task agent to audit Dockerfiles for size, security, and caching
- Compose exploration: Use
Explore agent to discover existing Docker configurations
- Architecture decisions: Use
Plan agent for container orchestration strategy
If the ci-cd-architecture skill is available, delegate CI/CD pipeline and deployment strategy to it.
If the application-security skill 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
1---
2name: docker
3description: |
4 Docker containerization for development and production. Covers Dockerfiles, multi-stage builds, layer caching, Compose services, networking, volumes, health checks, security hardening, and production deployment patterns.
5
6 Use when writing Dockerfiles, optimizing image size, configuring Compose services, debugging container networking, setting up health checks, hardening containers for production, or troubleshooting build cache issues.
7license: MIT
8metadata:
9 author: oakoss
10 version: '1.1'
11 source: 'https://docs.docker.com'
12user-invocable: false
13---
14
15# Docker
16
17## Overview
18
19Docker 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.
20
21**When to use:** Containerizing applications, creating reproducible dev environments, orchestrating multi-service stacks, deploying to container platforms (ECS, Kubernetes, Fly.io, Railway, Coolify).
22
23**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.
24
25## Quick Reference
26
27| Pattern | Approach | Key Points |
28| -------------------- | ---------------------------------------------- | ---------------------------------------------------- |
29| Multi-stage build | Separate `builder` and `production` stages | 80%+ image size reduction, no dev deps in production |
30| Layer caching | Copy lockfile first, install, then copy source | Dependency layer cached across builds |
31| Non-root user | `RUN adduser` + `USER` in final stage | Never run production containers as root |
32| Health check | `HEALTHCHECK CMD curl` or node/python check | Enables orchestrator restart on failure |
33| `.dockerignore` | Exclude `node_modules`, `.git`, `.env` | Smaller build context, faster builds |
34| Compose services | `compose.yaml` with service definitions | Dev environment in one command |
35| Compose override | `compose.prod.yaml` with production settings | Environment-specific config without duplication |
36| Named volumes | `volumes:` in Compose for persistent data | Survives container recreation |
37| Build cache mount | `RUN --mount=type=cache,target=/root/.npm` | Persistent cache across builds |
38| Secrets in build | `RUN --mount=type=secret,id=token` | Never bake secrets into image layers |
39| Image pinning | Pin to major.minor or digest | Reproducible builds, avoid surprise breakage |
40| Container networking | Custom bridge networks with service discovery | Containers resolve each other by service name |
41| Compose watch | `develop.watch` with sync/rebuild actions | Live reload without volume mounts |
42| Init process | `--init` flag or `tini` entrypoint | Proper signal handling and zombie reaping |
43| Multi-platform | `docker buildx build --platform` | ARM (Apple Silicon, Graviton) + x86 in one image |
44| Monorepo prune | `turbo prune app --docker` | Minimal build context from workspace dependencies |
45| CI layer caching | `cache-from`/`cache-to` with GHA or registry | Avoid full rebuilds in CI pipelines |
46| Debug containers | `docker exec`, `docker logs`, `dive` | Inspect running containers and image layers |
47
48## Common Mistakes
49
50| Mistake | Correct Pattern |
51| ----------------------------------------------- | ---------------------------------------------------------------- |
52| Installing dev dependencies in production image | Multi-stage build: install in builder, copy artifacts to runtime |
53| Copying source before installing dependencies | Copy lockfile first, `npm ci`, then copy source for cache reuse |
54| Running as root in production | Create non-root user, `USER` directive in final stage |
55| Hardcoding secrets in Dockerfile or ENV | Use build secrets (`--mount=type=secret`) or runtime env |
56| Using `latest` tag for base images | Pin to specific version (`node:24-alpine`) |
57| No `.dockerignore` file | Exclude `node_modules`, `.git`, `.env`, build artifacts |
58| Using `npm install` instead of `npm ci` | `npm ci` for deterministic, lockfile-based installs |
59| HEALTHCHECK missing | Add health check for orchestrator integration |
60| Large base images (`node:24`) | Use alpine variants (`node:24-alpine`) for smaller images |
61| Ignoring `.env` file precedence in Compose | `environment:` in Compose overrides `.env` file values |
62| Building entire monorepo for one service | Use `turbo prune --docker` for minimal build context |
63| No layer caching in CI | Use `cache-from`/`cache-to` with GHA or registry backend |
64| Building only for x86 when deploying to ARM | Use `docker buildx` with `--platform linux/amd64,linux/arm64` |
65
66## Delegation
67
68- **Dockerfile review**: Use `Task` agent to audit Dockerfiles for size, security, and caching
69- **Compose exploration**: Use `Explore` agent to discover existing Docker configurations
70- **Architecture decisions**: Use `Plan` agent for container orchestration strategy
71
72> If the `ci-cd-architecture` skill is available, delegate CI/CD pipeline and deployment strategy to it.
73> If the `application-security` skill is available, delegate container security scanning and hardening review to it.
74
75## References
76
77- [Dockerfile patterns: multi-stage builds, layer caching, and image optimization](references/dockerfile-patterns.md)
78- [Compose: services, networking, volumes, and environment management](references/compose.md)
79- [Security: non-root users, secrets, scanning, and production hardening](references/security.md)
80- [Buildx: multi-platform builds for ARM and x86](references/buildx-and-multiplatform.md)
81- [CI: GitHub Actions caching, registry push, and automated builds](references/ci-caching.md)
82- [Monorepo: Turborepo prune, pnpm workspaces, and selective builds](references/monorepo-builds.md)
83- [Debugging: logs, exec, inspect, layer analysis, and network troubleshooting](references/debugging.md)
oakoss