docker

---
name: docker
description: Use when writing or reviewing Dockerfiles, docker-compose files, or .dockerignore for any backend service. Covers multi-stage builds, container security hardening, compose orchestration, advanced build patterns, and a Docker review checklist for all 4 stacks: NestJS/Node 24, Spring Boot WebFlux 3.5.x/Java 21, Python FastAPI 3.14, and TypeScript/Fastify/Node 24.
allowed-tools: Bash, Read, Write, Edit
metadata:
  triggers: Dockerfile, docker-compose, containerize, docker build, multi-stage build, docker image, container, dockerignore, docker run, docker scout
  related-skills: java-spring-api, nestjs-api, python-dev, agentic-ai-dev, architecture-design
  domain: infrastructure
  role: specialist
  scope: implementation
  output-format: code
last-reviewed: "2026-03-14"
---

## Iron Law

**NO DOCKERFILE WITHOUT READING `reference/dockerfiles.md` FIRST — each stack has specific base images, build tools, and health check patterns that must be used exactly**

# Docker

Production-ready containerization for NestJS/Node 24, Spring Boot WebFlux 3.5.x/Java 21, Python FastAPI 3.14, and TypeScript/Fastify/Node 24. All patterns follow: multi-stage build, non-root user, HEALTHCHECK, .dockerignore.

## When to Use

- Writing a Dockerfile for any backend service
- Writing or updating docker-compose files for local dev or production
- Reviewing an existing Dockerfile for security, size, or correctness
- Adding build cache optimization (`--mount=type=cache`)
- Setting up Docker Compose secrets for production
- Building multi-architecture images (linux/amd64 + linux/arm64)
- Debugging container build failures, slow builds, or large image sizes

## How This Skill Relates to Others

| Skill | Scope |
|-------|-------|
| **docker** (this skill) | Container definitions, compose files, build patterns |
| **java-spring-api** | Java application code — loads docker skill for Dockerfile |
| **nestjs-api** | NestJS templates include Dockerfile — this skill extends those patterns |
| **python-dev** | FastAPI code — loads docker skill for Dockerfile |
| **agentic-ai-dev** | Python agent code — has deployment reference that this skill augments |

## Process

### Step 1: Choose the Right Dockerfile Pattern

Read `reference/dockerfiles.md` for the complete, copy-ready Dockerfile for your stack:

| Stack | Base Image | Build Tool | Port |
|-------|-----------|-----------|------|
| NestJS 11.x / Node 24 | node:24-alpine | pnpm | 3000 |
| Spring Boot WebFlux 3.5.x | maven:3.9-eclipse-temurin-21-alpine → eclipse-temurin:21-jre-alpine | Maven | 8080 |
| Python FastAPI 3.14 | python:3.14-slim | uv | 8000 |
| Python Agentic AI | python:3.14-slim | uv + gunicorn | 8000 |
| TypeScript/Fastify / Node 24 | node:24-alpine | npm | 3000 |

### Step 2: Set Up Docker Compose

Read `reference/compose-patterns.md` for:
- Development compose (PostgreSQL 17 + Redis 7)
- Production compose with Docker secrets (`_FILE` env pattern)
- Health check dependency ordering (`condition: service_healthy`)
- Network isolation (internal backend network)
- Resource limits and restart policies

### Step 3: Apply Advanced Patterns (if needed)

Read `reference/advanced-patterns.md` for:
- Build cache mounts (`--mount=type=cache`) for Maven, npm, pip/uv — cuts rebuild time significantly
- Multi-architecture builds (`docker buildx`) for linux/amd64 + linux/arm64
- Distroless runtime images for zero-CVE base
- Build-time secrets (BuildKit `--mount=type=secret`)
- Diagnostics: slow builds, large images, networking failures, hot-reload issues

### Step 4: Review with Checklist

Read `assets/docker-review-checklist.md` before committing any Dockerfile or compose file. Covers 6 categories: optimization, security, compose, image size, dev workflow, networking.

## Reference Files

| File | Content | Load When |
|------|---------|-----------|
| `reference/dockerfiles.md` | Copy-ready multi-stage Dockerfiles + .dockerignore for all 5 stack variants | Writing any new Dockerfile |
| `reference/compose-patterns.md` | Dev compose (PostgreSQL+Redis), production compose with Docker secrets, health checks, networks, resource limits | Writing or reviewing docker-compose files |
| `reference/advanced-patterns.md` | Build cache mounts (all stacks), multi-arch buildx, distroless images, build secrets, diagnostics | Optimizing builds or debugging container issues |
| `assets/docker-review-checklist.md` | 30-item Docker review checklist (6 categories) with stack-specific items | Before committing Dockerfile or compose changes |

## Error Handling

**Build fails with "not found" or permission error**: Check .dockerignore is not excluding required files. Verify COPY paths match actual project structure.

**Image too large (>500MB for Node/Python, >300MB for Java runtime)**: Read `reference/advanced-patterns.md` section "Image Size Optimization" — switch to multi-stage if single-stage, or distroless runtime.

**Container exits immediately**: Check HEALTHCHECK target path matches the actual health endpoint. Verify USER directive comes after all COPY operations. Check CMD vs ENTRYPOINT usage.

**docker-compose: service fails to connect to database**: Verify `depends_on: condition: service_healthy` is set. Verify DATABASE_URL credentials match docker-compose environment values exactly.

More agent context in kumaran-is/claude-code-onboarding

157 other files this repository gives its agents, the first 60 shown.