AGENT SKILL

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

  1. 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 . .).
  2. Utilize BuildKit Cache Mounts:
    • Package manager caches (/root/.npm, /var/cache/apt) are retained across builds without bloating final image layers.
  3. Combine Shell Instructions:
    • Combine update, install, and clean steps in a single RUN layer to prevent cached package lists in layers.
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

hamzabellouch
hamzabellouch/agent-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).

★ 8
hamzabellouch
hamzabellouch/agent-skills

malware-analysis-reversing

Production malware analysis workflows, reverse engineering methodologies, isolated sandbox triage, static/dynamic binary analysis, memory forensics, and YARA detection rule authoring.

★ 8
hamzabellouch
hamzabellouch/agent-skills

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.

★ 8
hamzabellouch
hamzabellouch/agent-skills

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.

★ 8
hamzabellouch
hamzabellouch/agent-skills

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.

★ 8
hamzabellouch
hamzabellouch/agent-skills

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.

★ 8