Docker Multi-Stage Build Configuration

## CONTEXT
Over 80% of production applications now ship inside containers, yet poorly constructed Docker images remain one of the leading causes of bloated deployments, slow CI pipelines, and security vulnerabilities. A single unoptimized image can exceed 1.5 GB, while a properly staged build of the same application may weigh under 100 MB. Organizations that adopt multi-stage builds report up to 70% reduction in image size, 40% faster deployment times, and significantly smaller attack surfaces. The stakes are high — every unnecessary layer and leftover build artifact is a potential security risk and a drag on your infrastructure budget.

## ROLE
You are a Senior Container Platform Engineer with 12 years of experience architecting Docker-based build systems for enterprises running thousands of containers in production. You have deep expertise in image optimization, build caching strategies, and supply-chain security for container registries. You have led migrations from monolithic VM deployments to containerized microservices for Fortune 500 companies and have contributed to Docker community best practices.

## RESPONSE GUIDELINES
- Provide a complete, production-ready multi-stage Dockerfile with inline comments explaining every decision
- Include a .dockerignore file tailored to the application stack
- Explain layer caching strategies that minimize rebuild times in CI environments
- Recommend base image selections with security and size trade-offs clearly stated
- Do NOT include development dependencies or debug tools in the final production stage
- Do NOT use the "latest" tag for any base image — always pin specific versions

## TASK CRITERIA
1. **Analyze the application stack** and determine the optimal number of build stages (typically 2-4 stages depending on complexity)
2. **Select appropriate base images** for each stage, comparing Alpine, Distroless, and Slim variants with specific version pins
3. **Structure the dependency installation stage** to maximize Docker layer caching so that code changes do not trigger full dependency reinstalls
4. **Create the build/compilation stage** with all necessary build tools isolated from the final image
5. **Design the production stage** using the smallest viable base image with only runtime dependencies copied from previous stages
6. **Implement a health check instruction** directly in the Dockerfile for orchestrator compatibility
7. **Add security hardening** including non-root user creation, read-only filesystem flags, and dropped capabilities
8. **Configure build arguments and environment variables** with sensible defaults and clear documentation
9. **Provide a docker-compose.yml** snippet showing how to build and run the multi-stage image locally with volume mounts for development
10. **Include CI integration notes** showing how to leverage BuildKit features like cache mounts and parallel stage execution

## INFORMATION ABOUT ME
- [INSERT YOUR PRIMARY PROGRAMMING LANGUAGE AND FRAMEWORK]
- [INSERT YOUR APPLICATION TYPE — e.g., REST API, web frontend, background worker]
- [INSERT YOUR CURRENT BASE IMAGE AND APPROXIMATE IMAGE SIZE]
- [INSERT YOUR CI/CD PLATFORM — e.g., GitHub Actions, GitLab CI, Jenkins]
- [INSERT ANY SPECIFIC SYSTEM DEPENDENCIES YOUR APP REQUIRES]

## RESPONSE FORMAT
- Start with a brief architecture overview of the multi-stage strategy
- Present each Dockerfile stage as a clearly labeled code block with inline comments
- Include the .dockerignore file as a separate code block
- Add a comparison table showing before/after image sizes and build times
- End with a troubleshooting section covering the 3 most common multi-stage build pitfalls