AI-Powered Docker v25 Dockerfile Optimization: A Guide to Multi-Stage Builds

# ❌ Inefficient single-stage Dockerfile
FROM node:18
WORKDIR /app

# AI detects: Installing dev dependencies in production image
COPY package*.json ./
RUN npm install

# AI detects: Copying unnecessary files
COPY . .

# AI detects: No build optimization
RUN npm run build

# AI detects: Running as root user
EXPOSE 3000
CMD ["npm", "start"]

# Problems detected by AI:
# - Large base image with unnecessary tools
# - Dev dependencies included in final image
# - No layer caching optimization
# - Security vulnerabilities (root user)
# - No health checks or proper signal handling

# ✅ AI-optimized multi-stage Dockerfile
# Stage 1: Dependencies and build (AI-optimized base)
FROM node:18-alpine AS dependencies
WORKDIR /app

# AI suggests: Copy package files first for better caching
COPY package*.json ./
COPY yarn.lock* ./

# AI suggests: Install only production dependencies
RUN npm ci --only=production && npm cache clean --force

# Stage 2: Build stage (AI-optimized for build tools)
FROM node:18-alpine AS builder
WORKDIR /app

# AI suggests: Copy package files and install all dependencies
COPY package*.json ./
COPY yarn.lock* ./
RUN npm ci

# AI suggests: Copy source code and build
COPY . .
RUN npm run build && npm run test:unit

# Stage 3: Production image (AI-optimized minimal runtime)
FROM node:18-alpine AS production

# AI suggests: Create non-root user for security
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nextjs -u 1001

WORKDIR /app

# AI suggests: Copy only necessary files from previous stages
COPY --from=dependencies --chown=nextjs:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=nextjs:nodejs /app/dist ./dist
COPY --from=builder --chown=nextjs:nodejs /app/public ./public
COPY --chown=nextjs:nodejs package*.json ./

# AI suggests: Switch to non-root user
USER nextjs

# AI suggests: Expose port and add health check
EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:3000/health || exit 1

# AI suggests: Proper signal handling
CMD ["node", "dist/server.js"]

# AI-generated .dockerignore optimization
# node_modules
# npm-debug.log*
# .git
# .gitignore
# README.md
# Dockerfile*
# .dockerignore
# .env
# coverage/
# .nyc_output
# .cache/
# .parcel-cache/
# .DS_Store
# *.log

# AI-optimized build caching strategies

# Multi-architecture build with optimized caching
FROM --platform=$BUILDPLATFORM node:18-alpine AS base
ARG TARGETPLATFORM
ARG BUILDPLATFORM

# AI suggests: Install build dependencies efficiently
RUN apk add --no-cache \
    ca-certificates \
    curl \
    && rm -rf /var/cache/apk/*

WORKDIR /app

# Stage 1: Package installation with maximum caching
FROM base AS deps

# AI suggests: Copy lockfiles first for better cache hits
COPY package.json package-lock.json* yarn.lock* pnpm-lock.yaml* ./

# AI suggests: Conditional package manager detection
RUN \
  if [ -f yarn.lock ]; then yarn --frozen-lockfile; \
  elif [ -f package-lock.json ]; then npm ci; \
  elif [ -f pnpm-lock.yaml ]; then yarn global add pnpm && pnpm i --frozen-lockfile; \
  else echo "Lockfile not found." && exit 1; \
  fi

# Stage 2: Source and build with optimized layers
FROM base AS builder

# AI suggests: Copy dependencies from cache-optimized stage
COPY --from=deps /app/node_modules ./node_modules

# AI suggests: Copy source files in optimal order for caching
COPY tsconfig.json next.config.js ./
COPY public ./public
COPY src ./src

# AI suggests: Conditional build optimization
ARG NODE_ENV=production
ENV NODE_ENV=$NODE_ENV

# AI suggests: Build with optimization flags
RUN \
  if [ "$NODE_ENV" = "production" ]; then \
    npm run build:prod; \
  else \
    npm run build; \
  fi

# Stage 3: Runtime optimization
FROM node:18-alpine AS runner

# AI suggests: Install only runtime dependencies
RUN apk add --no-cache \
    dumb-init \
    curl \
    && rm -rf /var/cache/apk/*

# AI suggests: Create optimized user
RUN addgroup --system --gid 1001 nodejs && \
    adduser --system --uid 1001 nextjs

WORKDIR /app

# AI suggests: Set optimal environment variables
ENV NODE_ENV=production
ENV PORT=3000
ENV HOSTNAME=0.0.0.0

# AI suggests: Copy built application with proper permissions
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
COPY --from=builder --chown=nextjs:nodejs /app/public ./public

USER nextjs

# AI suggests: Use dumb-init for proper signal handling
ENTRYPOINT ["dumb-init", "--"]

# AI suggests: Optimized health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:$PORT/api/health || exit 1

EXPOSE $PORT

CMD ["node", "server.js"]

# AI-generated security-hardened Dockerfile

# Use specific version tags for reproducibility
FROM node:18.19.0-alpine3.19 AS base

# AI suggests: Security labels for compliance
LABEL maintainer="devops-team@company.com" \
      version="1.0.0" \
      description="Production-ready Node.js application" \
      security.scan="enabled"

# AI suggests: Install security updates
RUN apk update && \
    apk upgrade && \
    apk add --no-cache \
        ca-certificates \
        curl \
        dumb-init \
    && rm -rf /var/cache/apk/*

# Stage 1: Security-first dependency installation
FROM base AS secure-deps

WORKDIR /app

# AI suggests: Verify package integrity
COPY package*.json ./
RUN npm audit --audit-level=moderate && \
    npm ci --only=production && \
    npm cache clean --force

# Stage 2: Secure build environment
FROM base AS secure-builder

WORKDIR /app

# AI suggests: Copy with verification
COPY package*.json ./
RUN npm ci

# AI suggests: Code quality and security checks
COPY . .
RUN npm run lint && \
    npm run test:security && \
    npm audit --audit-level=high && \
    npm run build

# Stage 3: Minimal production runtime
FROM gcr.io/distroless/nodejs18-debian11:nonroot AS production

# AI suggests: Copy from previous stages only what's needed
COPY --from=secure-deps --chown=nonroot:nonroot /app/node_modules ./node_modules
COPY --from=secure-builder --chown=nonroot:nonroot /app/dist ./dist
COPY --from=secure-builder --chown=nonroot:nonroot /app/package.json ./

# AI suggests: Use distroless for minimal attack surface
USER nonroot

EXPOSE 3000

# AI suggests: Read-only filesystem for security
# --read-only flag should be used at runtime

CMD ["dist/server.js"]

# AI-generated security scanning configuration
# .securityignore
*.md
*.txt
.git/
.github/
docs/
examples/
tests/
*.test.js
*.spec.js

# AI-generated Dockerfile linting rules
# hadolint ignore=DL3008,DL3009,DL3015
# DL3008: Pin versions in apt get install
# DL3009: Delete apt-get lists after installing
# DL3015: Avoid additional packages by specifying --no-install-recommends

# AI-optimized build performance techniques

# BuildKit specific optimizations
# syntax=docker/dockerfile:1.6

FROM node:18-alpine AS base

# AI suggests: Enable BuildKit mount caches
RUN --mount=type=cache,target=/var/cache/apk \
    apk add --no-cache curl ca-certificates

WORKDIR /app

# Stage 1: Dependency caching with BuildKit
FROM base AS deps

# AI suggests: Use bind mounts for better caching
RUN --mount=type=bind,source=package.json,target=package.json \
    --mount=type=bind,source=package-lock.json,target=package-lock.json \
    --mount=type=cache,target=/root/.npm \
    npm ci --prefer-offline --no-audit

# Stage 2: Build with advanced caching
FROM base AS builder

# AI suggests: Copy node_modules from cache
COPY --from=deps /app/node_modules ./node_modules

# AI suggests: Use bind mount for source code
RUN --mount=type=bind,source=.,target=.,rw \
    --mount=type=cache,target=/app/.next/cache \
    npm run build

# Stage 3: Production with multi-arch support
FROM --platform=$TARGETPLATFORM node:18-alpine AS production

# AI suggests: Platform-specific optimizations
ARG TARGETPLATFORM
RUN echo "Building for $TARGETPLATFORM"

# AI suggests: Conditional binary installation
RUN case "$TARGETPLATFORM" in \
      "linux/amd64") \
        echo "Optimizing for amd64" && \
        apk add --no-cache libc6-compat ;; \
      "linux/arm64") \
        echo "Optimizing for arm64" && \
        apk add --no-cache libc6-compat ;; \
      *) \
        echo "Generic optimization" ;; \
    esac

# AI suggests: Create user with optimal settings
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nextjs -u 1001 -G nodejs

WORKDIR /app

# AI suggests: Parallel copy operations
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

# AI suggests: Optimized startup
CMD ["node", "server.js"]