docker-multi-stage-builds
Master production Docker multi-stage builds, container image layer caching, security hardening, non-root user execution, distroless images, and minimal footprint optimizations. Trigger when building Dockerfiles, optimizing image size, or hardening container runtime security.
- License 许可
- MIT
- 最近更新
- 2026-10-17
- Stars
- ★ 8
- Forks
- 1
01 前言 Front Matter
- name
- docker-multi-stage-builds
- metadata
- { "category": "Containerization and Orchestration" }
- description
- Master production Docker multi-stage builds, container image layer caching, security hardening, non-root user execution, distroless images, and minimal footprint optimizations. Trigger when building Dockerfiles, optimizing image size, or hardening container runtime security.
- compatibility
- Docker Engine 20.10+, BuildKit, Docker Compose v2+
03 SKILL.md 正文
Docker Multi-Stage Builds & Optimization Skill Guide
This skill defines production standards for authoring secure, minimal-footprint, highly cached multi-stage Dockerfile definitions.
1. Multi-Stage Build Architecture
Multi-stage builds separate compilation environments (which contain full SDKs and build tools) from final production runtime containers (which contain only compiled artifacts and runtime dependencies).
+-------------------------------------------------------------+
| Stage 1: Build & Dependencies (golang:1.22-alpine / node:20) |
| - Full toolchain, build tools, package managers |
| - Compiles binary / bundle |
+-------------------------------------------------------------+
|
Copy Artifacts Only
v
+-------------------------------------------------------------+
| Stage 2: Production Runtime (gcr.io/distroless or alpine) |
| - No shell, no package manager, non-root system user |
| - Minimal image size (<30MB) |
+-------------------------------------------------------------+
2. Production Multi-Stage Dockerfile Patterns
A. Node.js / Next.js Production Dockerfile
# Syntax directive required for modern BuildKit cache features
# syntax=docker/dockerfile:1.6
# -------------------------------------------------------------
# Base Stage: Shared node environment
# -------------------------------------------------------------
FROM node:20-alpine AS base
WORKDIR /app
RUN apk add --no-libc-compat
# -------------------------------------------------------------
# Stage 1: Install Dependencies with Layer Caching
# -------------------------------------------------------------
FROM base AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
npm ci --only=production
# -------------------------------------------------------------
# Stage 2: Build Application
# -------------------------------------------------------------
FROM base AS builder
WORKDIR /app
COPY package.json package-lock.json ./
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ENV NODE_ENV=production
RUN --mount=type=cache,target=/root/.npm \
npm run build
# -------------------------------------------------------------
# Stage 3: Minimal Production Runtime
# -------------------------------------------------------------
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV PORT=3000
# Create dedicated non-root user and group
RUN addgroup --system --gid 1001 nodejs && \
adduser --system --uid 1001 nextjs
# Copy built application assets with ownership settings
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
USER nextjs
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD wget --no-verbose --tries=1 --spider http://localhost:3000/api/health || exit 1
CMD ["node", "server.js"]
B. Go Microservice Distroless Dockerfile
# syntax=docker/dockerfile:1.6
# -------------------------------------------------------------
# Stage 1: Build Go Binary
# -------------------------------------------------------------
FROM golang:1.22-alpine AS builder
WORKDIR /src
# Download modules with BuildKit cache
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod \
go mod download
COPY . .
# Compile static binary disabling cgo and strip symbols (-s -w)
RUN --mount=type=cache,target=/go/pkg/mod \
--mount=type=cache,target=/root/.cache/go-build \
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
go build -ldflags="-s -w" -o /bin/server ./cmd/server
# -------------------------------------------------------------
# Stage 2: Distroless Minimal Security Runtime
# -------------------------------------------------------------
FROM gcr.io/distroless/static-debian12:nonroot AS runner
WORKDIR /
COPY --from=builder --chown=nonroot:nonroot /bin/server /server
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/server"]
3. Image Optimization & Layer Ordering Rules
- Order from Least to Most Frequently Changed:
- Install system dependencies first (
apt-get,apk). - Copy lock files second (
package-lock.json,go.sum). - Copy application source code last (
COPY . .).
- Install system dependencies first (
- Utilize BuildKit Cache Mounts:
- Package manager caches (
/root/.npm,/var/cache/apt) are retained across builds without bloating final image layers.
- Package manager caches (
- Combine Shell Instructions:
- Combine update, install, and clean steps in a single
RUNlayer to prevent cached package lists in layers.
- Combine update, install, and clean steps in a single
RUN apt-get update && apt-get install -y --no-install-recommends \
ca-certificates \
curl \
&& rm -rf /var/lib/apt/lists/*
4. Security Hardening & Image Inspection Commands
# Enable BuildKit CLI support
export DOCKER_BUILDKIT=1
# Build image with inline build cache support
docker buildx build \
--build-arg NODE_ENV=production \
--cache-to type=inline \
--tag my-app:2.1.0 \
.
# Scan image for vulnerabilities using Trivy
trivy image --severity HIGH,CRITICAL my-app:2.1.0
# Inspect image layer composition and size breakdown
docker history my-app:2.1.0
5. Anti-Patterns & Best Practices
| Anti-Pattern | Security / Performance Risk | Production Best Practice |
|---|---|---|
Running containers as default root user |
Container escape vulnerabilities compromise host kernel privilege. | Enforce USER nonroot or explicit UID (USER 10001). |
| Including SDK tools in final stage | Increases attack surface and image size (500MB+ vs 20MB). | Copy static binaries/bundles into distroless or minimal alpine base. |
COPY . . before npm install or go mod download |
Invalidates layer cache on any file change, forcing re-download of modules. | Copy dependency manifests (package.json, go.mod) prior to copying code. |
Omitting .dockerignore file |
Secrets, .git, node_modules, and local logs are baked into build context. |
Always create a .dockerignore excluding .git, node_modules, .env. |
04 同仓库更多 Skills
security-audit
Comprehensive security guidance, source code audit, vulnerability assessment, and penetration test review for codebases, APIs, microservices, CLI tools, libraries, and LLM-backed applications. Triggers on requests to audit a codebase, conduct security reviews, find vulnerabilities or flaws, pen-test source code, or when the user asks in Arabic (فحص أمني، تدقيق الكود أمنياً، مراجعة الثغرات، فحص أمان المشروع). Supports Guidance mode (focused review) and Full Audit mode (deterministic 6-phase harness).
malware-analysis-reversing
Production malware analysis workflows, reverse engineering methodologies, isolated sandbox triage, static/dynamic binary analysis, memory forensics, and YARA detection rule authoring.
application-security-pentesting
Production Application Security (AppSec) standards, OWASP Top 10 vulnerability remediation, SAST/DAST pipeline integration, secure code review, threat modeling, and defensive security posture.
oauth2-oidc-security-flows
Implement enterprise OAuth 2.1 and OpenID Connect (OIDC) authorization code flow with Proof Key for Code Exchange (PKCE), state and nonce verification, refresh token rotation, token revocation, and centralized IdP federation (Keycloak, Auth0, Okta). Trigger when building secure authentication, single sign-on (SSO), or third-party delegated authorization.
jwt-session-management-hardening
Harden JWT-based authentication and session lifecycles using asymmetric signing (RS256/EdDSA), JWKS rotation, strict claims validation, Redis-backed sliding window sessions, revocation lists, and secure HttpOnly cookie storage. Trigger when implementing token validation, session revocation, or hardening API authentication.
soc2-compliance-automation
Best practices for implementing SOC 2 Type II compliance controls, continuous evidence collection, infrastructure policy-as-code, and automated security monitoring. Use when automating Trust Services Criteria (Security, Availability, Confidentiality, Processing Integrity, Privacy), audit logging, IAM least privilege, or CI/CD security gates.