multi-stage-dockerfile

github/awesome-copilot

Create optimized multi-stage Dockerfiles that reduce image size and improve security across any language or framework.

What is multi-stage-dockerfile?

This skill helps you build efficient multi-stage Dockerfiles following best practices. It guides you through structuring builder and runtime stages, selecting minimal base images, optimizing layers for caching, and implementing security hardening to produce smaller, more secure container images.

Design multi-stage Dockerfile structure with separate builder and runtime stages
Select appropriate base images with exact version tags and consider distroless or Alpine variants
Optimize Docker layers for caching by ordering commands from least to most frequently changing
Implement security practices including non-root users, vulnerability scanning, and build secret isolation
Configure build arguments, environment variables, and healthchecks for production readiness
Reduce final image size by copying only necessary artifacts from builder to runtime stage

How to install multi-stage-dockerfile

npx skills add https://github.com/github/awesome-copilot --skill multi-stage-dockerfile

Claude Code

Cursor

Windsurf

Cline

How to use multi-stage-dockerfile

1.Define your builder stage with a meaningful name using FROM...AS syntax and include all build dependencies
2.Add compilation or build steps in the builder stage, organizing RUN commands by change frequency
3.Create a separate runtime stage using a minimal base image with exact version tags
4.Copy only necessary artifacts from the builder stage using COPY --from=builder
5.Add a non-root USER instruction and set appropriate environment variables like NODE_ENV=production
6.Include a HEALTHCHECK instruction appropriate for your application type
7.Review the final image to ensure build tools and unnecessary packages are excluded

Use cases

Good for

Building Node.js applications with separate dependency installation and production stages
Creating Python images that exclude development tools from the final runtime image
Optimizing Go or Java applications by compiling in a builder stage and running minimal binaries
Reducing image size for microservices by using distroless base images for runtime
Setting up CI/CD pipelines with reproducible builds using pinned base image versions

Who it's for

Backend developers building containerized applications
DevOps engineers optimizing container image size and security
Full-stack developers working with Docker in development and production
Teams implementing container security scanning and compliance requirements

multi-stage-dockerfile FAQ

Why use multi-stage builds instead of a single Dockerfile?

Multi-stage builds separate build-time dependencies from runtime requirements, allowing you to exclude compilers, build tools, and development packages from the final image. This significantly reduces image size, improves security by removing unnecessary attack surface, and keeps production images lean.

What base image should I use for the runtime stage?

Use official minimal base images with exact version tags (e.g., python:3.11-slim). Consider distroless images if your application doesn't need a shell or package manager. Alpine-based images offer smaller footprints but verify compatibility with your application dependencies.

How do I ensure Docker layer caching works efficiently?

Order your Dockerfile commands from least to most frequently changing. Place dependency installation before code COPY statements, combine related RUN commands with &&, and use .dockerignore to exclude unnecessary files from the build context.

How can I prevent build secrets from leaking into the final image?

Use multi-stage builds to keep secrets in the builder stage only. Never COPY sensitive files into the runtime stage. For build-time secrets, use Docker BuildKit's --secret flag instead of ENV variables.

What security practices should I implement?

Run containers as non-root using the USER instruction, remove build tools from the final image, scan for vulnerabilities, set restrictive file permissions, and avoid including unnecessary packages in the runtime stage.

Full instructions (SKILL.md)

Source of truth, from github/awesome-copilot.

name: multi-stage-dockerfile description: 'Create optimized multi-stage Dockerfiles for any language or framework'

Your goal is to help me create efficient multi-stage Dockerfiles that follow best practices, resulting in smaller, more secure container images.

Multi-Stage Structure

Use a builder stage for compilation, dependency installation, and other build-time operations
Use a separate runtime stage that only includes what's needed to run the application
Copy only the necessary artifacts from the builder stage to the runtime stage
Use meaningful stage names with the AS keyword (e.g., FROM node:18 AS builder)
Place stages in logical order: dependencies → build → test → runtime

Base Images

Start with official, minimal base images when possible
Specify exact version tags to ensure reproducible builds (e.g., python:3.11-slim not just python)
Consider distroless images for runtime stages where appropriate
Use Alpine-based images for smaller footprints when compatible with your application
Ensure the runtime image has the minimal necessary dependencies

Layer Optimization

Organize commands to maximize layer caching
Place commands that change frequently (like code changes) after commands that change less frequently (like dependency installation)
Use .dockerignore to prevent unnecessary files from being included in the build context
Combine related RUN commands with && to reduce layer count
Consider using COPY --chown to set permissions in one step

Security Practices

Avoid running containers as root - use USER instruction to specify a non-root user
Remove build tools and unnecessary packages from the final image
Scan the final image for vulnerabilities
Set restrictive file permissions
Use multi-stage builds to avoid including build secrets in the final image

Performance Considerations

Use build arguments for configuration that might change between environments
Leverage build cache efficiently by ordering layers from least to most frequently changing
Consider parallelization in build steps when possible
Set appropriate environment variables like NODE_ENV=production to optimize runtime behavior
Use appropriate healthchecks for the application type with the HEALTHCHECK instruction

Surgical code refactoring to improve maintainability without changing behavior.

19k installsAudited