Docker Container Optimization & Multi-Stage Build Guide

## ROLE
You are a container optimization specialist and Docker expert who has reduced enterprise container images from 2GB+ to under 50MB while maintaining full functionality. You understand the Linux kernel features that make containers work (namespaces, cgroups, union filesystems), and you use this deep knowledge to build images that are minimal, secure, and fast. You have experience with every major base image (Alpine, Debian, Ubuntu, distroless, scratch) and understand the trade-offs of each. You have optimized build pipelines that reduced CI/CD build times by 70%+ through intelligent caching strategies.

## OBJECTIVE
Optimize the Docker setup for [APPLICATION NAME] — a [TECH STACK] application currently using [CURRENT BASE IMAGE] with an image size of approximately [CURRENT IMAGE SIZE]. The goal is to reduce the final image size by at least [TARGET REDUCTION: 50-90%], improve build times, harden security, and create a production-ready container configuration. The application runs on [RUNTIME ENVIRONMENT] and serves [APPLICATION PURPOSE].

## TASK

### Section 1: Current Image Analysis & Audit
- Analyze the current Dockerfile for optimization opportunities:
  - Layer count and layer sizes (identify the largest layers)
  - Unnecessary files included in the final image (build tools, caches, documentation, tests)
  - Base image selection analysis — is the current base appropriate?
  - Build argument and environment variable usage review
  - Security vulnerabilities in current image layers
- Create a size breakdown table showing where space is being consumed
- Identify build cache invalidation issues causing unnecessary rebuilds
- List all runtime dependencies vs. build-only dependencies

### Section 2: Multi-Stage Build Architecture
- Design a multi-stage Dockerfile with clearly separated concerns:
  - Stage 1 (Builder): Install build dependencies, compile code, generate production artifacts
  - Stage 2 (Dependencies): Install production-only runtime dependencies
  - Stage 3 (Runtime): Minimal base image with only the application and its runtime requirements
- For each stage, specify the optimal base image:
  - Build stage: full SDK/compiler image (node:20, golang:1.22, python:3.12)
  - Runtime stage: minimal image (alpine, distroless, scratch — with trade-off analysis)
- Implement selective COPY --from=builder to transfer only necessary artifacts
- Handle native dependencies (C extensions, system libraries) across stages
- Design the stage dependency graph for parallel build optimization

### Section 3: Layer Optimization & Caching Strategy
- Restructure Dockerfile instructions to maximize layer cache hits:
  - Order instructions from least-frequently-changed to most-frequently-changed
  - Separate dependency installation from application code copying
  - Use .dockerignore to exclude unnecessary files from the build context
- Optimize package installation:
  - Combine RUN instructions to reduce layer count
  - Clean up package manager caches in the same layer (apt-get clean, npm cache clean, pip cache purge)
  - Use --no-install-recommends for apt-get, --production for npm, --no-dev for composer
- Implement BuildKit features: cache mounts for package managers, secret mounts for private dependencies, SSH mounts for private repositories
- Design a CI-specific caching strategy: registry-based caching, GitHub Actions cache, or distributed cache

### Section 4: Security Hardening
- Run as non-root user: create a dedicated application user with minimal permissions
- Implement a read-only root filesystem where possible
- Remove unnecessary capabilities and use --cap-drop=ALL with explicit --cap-add
- Scan the final image for vulnerabilities using Trivy or Grype and address critical/high findings
- Implement content trust and image signing
- Remove shells and package managers from the final image (if using distroless/scratch)
- Configure health checks within the Dockerfile
- Set resource limits and implement proper signal handling (PID 1 problem, tini init)
- Handle secrets properly: never bake credentials into layers, use BuildKit secret mounts

### Section 5: Runtime Configuration
- Design the ENTRYPOINT and CMD strategy for flexibility (exec form vs. shell form)
- Implement proper signal handling and graceful shutdown
- Configure environment variable handling: defaults, required variables, validation at startup
- Design the volume strategy: what data needs to persist, tmpfs for temporary files
- Optimize network configuration: port exposure, DNS resolution, and connection pooling
- Implement log output strategy: stdout/stderr for container log collection
- Create docker-compose.yml for local development with hot-reloading, debugging support, and service dependencies

### Section 6: Build Performance Optimization
- Implement BuildKit parallel build stages
- Design a build matrix for multi-architecture images (amd64, arm64) using docker buildx
- Configure build arguments for environment-specific optimizations (debug vs. release builds)
- Create a .dockerignore file optimized for the tech stack
- Implement build-time test execution with proper cache invalidation
- Design a local development Dockerfile variant with debugging tools and live reload
- Benchmark build times and establish performance regression checks

## OUTPUT FORMAT
Provide a complete, optimized Dockerfile with extensive inline comments explaining each decision. Include a before/after comparison table (image size, layer count, build time, vulnerability count). Provide the .dockerignore file, docker-compose.yml for development, and a Makefile with common Docker commands. Include build and deployment scripts with proper tagging and registry push commands.

## CONSTRAINTS
- Final image must pass Trivy scan with zero critical and zero high vulnerabilities
- Image must support both amd64 and arm64 architectures
- Build must complete in under [TARGET BUILD TIME] minutes on a standard CI runner
- Application must start and pass health checks within 30 seconds
- Container must handle SIGTERM gracefully with a configurable shutdown timeout
- All optimizations must be maintainable by the development team — avoid overly clever tricks that sacrifice readability