/infra-ci-cd-docker

name: infra-ci-cd-docker
description: Docker containerization patterns for Node.js/TypeScript development and production

Docker Containerization Patterns

> **Quick Guide:** Docker with BuildKit for containerizing Node.js/TypeScript applications. Multi-stage builds for minimal production images (1GB to under 100MB). Docker Compose v2 for development environments. BuildKit cache mounts for 10x faster dependency installs. Non-root users, health checks, and secret mounts for production security. Alpine for size, Debian slim for compatibility.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use multi-stage builds for production images - NEVER ship dev dependencies, TypeScript compiler, or source files in production)**

**(You MUST run containers as non-root user - NEVER run production containers as root (default))**

**(You MUST use `CMD ["node", "server.js"]` (exec form) - NEVER use `npm start` or shell form as CMD)**

**(You MUST use BuildKit secret mounts for sensitive data at build time - NEVER use ARG or ENV for secrets)**

**(You MUST copy package.json/lockfile BEFORE source code - NEVER `COPY . .` before `npm ci` (breaks layer cache))**

</critical_requirements>

---

Examples

• [Dockerfile Patterns](examples/core.md) - Multi-stage builds, Bun, monorepo, layer caching, .dockerignore, signal handling
• [Docker Compose](examples/compose.md) - Development environments, networking, volumes, healthchecks
• [Production & CI/CD](examples/production.md) - Security hardening, secrets, CI/CD pipelines, vulnerability scanning
• [Quick Reference](reference.md) - Dockerfile instructions, CLI commands, base image comparison

---

**Auto-detection:** Dockerfile, docker-compose, compose.yaml, Docker, container, multi-stage build, BuildKit, .dockerignore, Docker Compose, docker build, docker run, HEALTHCHECK, Docker Scout, docker init, containerize, container image, Docker network, Docker volume

**When to use:**

• Creating Dockerfiles for Node.js/TypeScript applications
• Setting up multi-stage builds to minimize production image size
• Configuring Docker Compose for local development environments
• Optimizing Docker layer caching and BuildKit cache mounts
• Implementing container security (non-root, secrets, read-only filesystem)
• Setting up health checks for container orchestration
• Building CI/CD pipelines that build and push Docker images
• Teams needing consistent development environments across OS platforms
• Microservice architectures requiring isolated services with dependencies

**When NOT to use:**

• Serverless deployments (AWS Lambda, Vercel Functions) that don't use containers
• Static site hosting (Netlify, Vercel, Cloudflare Pages) with no server runtime
• Simple scripts or CLI tools distributed via npm
• Local development without containerization requirements
• When added complexity outweighs the isolation benefit
• Kubernetes-specific orchestration patterns (use a Kubernetes skill)

**Key patterns covered:**

• Multi-stage Dockerfile for Node.js/TypeScript (builder pattern)
• Docker Compose v2 development environments
• BuildKit cache mounts and layer optimization
• Container security (non-root, secrets, capabilities, read-only)
• Health checks for production containers
• `.dockerignore` for build context optimization
• Volume mounts (named volumes, bind mounts, tmpfs)
• Docker networking (bridge, host, overlay)
• CI/CD integration (GitHub Actions build-push)
• Signal handling (tini for graceful shutdown)

---

<philosophy>

Philosophy

Containers provide reproducible, isolated environments that eliminate "works on my machine" problems. Docker is the standard for packaging Node.js/TypeScript applications into portable, lightweight images.

**Core principles:**

1. **Minimal production images** - Ship only what the app needs to run (compiled JS, production deps, runtime) 2. **Layer cache optimization** - Structure Dockerfiles so unchanged layers are reused, making rebuilds fast 3. **Security by default** - Non-root users, no secrets in images, minimal attack surface 4. **Development parity** - Docker Compose mirrors production topology locally

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Multi-Stage Dockerfile for Node.js/TypeScript

Multi-stage builds compile TypeScript in a builder stage, then copy only compiled JS and production dependencies into a minimal runtime image. This reduces images from 1GB+ to under 100MB.

A production Dockerfile uses three stages:

1. **deps** - Install production dependencies only 2. **builder** - Install all dependencies, compile TypeScript 3. **runner** - Copy compiled output and production deps into minimal image

# Stage 1: Production dependencies
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci --omit=dev --no-audit --no-fund

# Stage 2: Build TypeScript
FROM node:22-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci --no-audit --no-fund
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build

# Stage 3: Production runtime
FROM node:22-alpine AS runner
WORKDIR /app
RUN apk add --no-cache tini
ENV NODE_ENV=production
RUN addgroup --system --gid 1001 appgroup && \
    adduser --system --uid 1001 --ingroup appgroup appuser
COPY --from=deps --chown=appuser:appgroup /app/node_modules ./node_modules
COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
COPY --chown=appuser:appgroup package.json ./
USER appuser
EXPOSE 3000
ENTRYPOINT ["/sbin/tini", "--"]
CMD ["node", "dist/server.js"]

**Why good:** Three-stage build separates concerns, BuildKit cache mount speeds up npm ci, non-root user, tini for signal handling, only production artifacts in final image

See [ex