docker

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

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 | | Configuring docker-compose for dev or production | references/compose-configs.md |

</references>