# Docker

> Docker containerization reference — multi-stage builds, Compose configs, image optimization, and container security for Yarn 4 monorepos. Use when: (1) creating or optimizing Dockerfiles, (2) configuring docker-compose for dev or production, (3) reducing image size with multi-stage builds, (4) hardening container security, or (5) setting up health checks and resource limits.

- Skill: `jgamaraalv/docker` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add jgamaraalv/docker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jgamaraalv/docker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: jgamaraalv (https://skillmd.com/u/jgamaraalv)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jgamaraalv/docker

---


# Docker — Containerization for Monorepos

Docker best practices for Node.js monorepos with Yarn 4 Berry.

<rules>

## Key Principles

- **Minimal images**: Alpine-based, only runtime dependencies in final stage
- **Layer caching order**: system deps → package manifests → install → source → build
- **Non-root users**: Create `app` user, never run as root in production
- **One process per container**: Compose multiple containers, not multiple processes
- **Health checks on every service**: Use the existing `/health` endpoint

## Image Optimization Quick Reference

- Use `node:22-alpine` as base
- Multi-stage builds: exclude build tools from final image
- `yarn cache clean` after install
- `.dockerignore`: exclude `.git`, `node_modules`, `*.md`, `.env*`, `.claude`, `__tests__`, `coverage`, `.turbo`
- `--production` flag for runtime dependencies only
- Pin base image versions (not just `latest`)

## Container Security Quick Reference

- Run as non-root user (`addgroup --system app && adduser --system --ingroup app app`)
- Don't store secrets in images — use env vars or secrets management
- Scan images: `docker scout cves <image>`
- Set resource limits in compose: `mem_limit`, `cpus`
- Read-only filesystem where possible: `read_only: true`
- Drop capabilities: `cap_drop: [ALL]`

</rules>

<quick_reference>

## Useful Commands

```bash
docker compose build api          # Build specific service
docker compose up -d              # Start all services
docker compose logs -f api        # Follow logs
docker compose exec api sh        # Shell into container
docker images | grep myapp    # Check image sizes
docker system df                  # View cache usage
docker system prune -a            # Prune unused images
docker stats                      # Resource usage
```

</quick_reference>

<references>

## When to Load References

| Need                                               | Reference file                                                         |
| -------------------------------------------------- | ---------------------------------------------------------------------- |
| Writing or reviewing a Dockerfile for the monorepo | [references/monorepo-dockerfile.md](references/monorepo-dockerfile.md) |
| Configuring docker-compose for dev or production   | [references/compose-configs.md](references/compose-configs.md)         |

</references>