Do I need a multi-stage Dockerfile for every app?

It's a best practice for most apps to reduce size and surface area; if your runtime can be produced in a single stage, you can still adopt separation to protect build-time assets and secrets.

How should base images be chosen and pinned?

Start with official minimal bases, pin exact tags (e.g., python:3.11-slim), and consider distroless for runtime when appropriate; use Alpine only if compatible with your app.

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

Use multi-stage builds to avoid copying secrets into the final image, and consider BuildKit secrets or ARGs for build-time values without persisting them in layers.

multi-stage-dockerfile

Scanned

npx machina-cli add skill github/awesome-copilot/multi-stage-dockerfile --openclaw

Files (1)

SKILL.md

2.3 KB

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

Source

git clone https://github.com/github/awesome-copilot/blob/main/plugins/devops-oncall/skills/multi-stage-dockerfile/SKILL.md

View on GitHub

Overview

This skill guides building efficient multi-stage Dockerfiles that split build-time tasks from runtime execution. It emphasizes using builder and runtime stages, precise base images, and layer and security best practices to produce smaller, safer images.

How This Skill Works

It uses a dedicated builder stage for compilation and dependency installation, then a lean runtime stage that only contains what's necessary to run the app. Stages are named with AS (e.g., FROM node:18 AS builder), and artifacts are copied across using minimal, well-scoped COPY commands to minimize final image size and surface area.

When to Use It

You need smaller production images across any language or framework
You want to separate build-time dependencies from runtime dependencies
You must prevent build tools or secrets from ending up in the final image
You require reproducible builds by pinning exact base image tags
You aim to optimize build cache and enable safer, faster builds

Quick Start

Step 1: Create two stages in your Dockerfile: a builder (AS builder) and a runtime (AS runtime)
Step 2: COPY only the built artifacts from --from=builder to --from=runtime, and use COPY --chown to set permissions
Step 3: Build with docker build -t your-app . and run with docker run your-app

Best Practices

Use a builder stage for compilation/dependency installation and a separate runtime stage for execution
Pin exact base image tags (e.g., python:3.11-slim) and consider distroless or Alpine where appropriate
Optimize layers by ordering less-frequently-changing steps first, using .dockerignore, and joining RUN commands with &&
Run as a non-root user (USER) and remove build tools from the final image; set restrictive file permissions
Leverage build args and environment variables for config; add HEALTHCHECKs and scan the final image for vulnerabilities

Example Use Cases

Node.js: Build dependencies in a builder stage (npm ci) and copy the built artifacts to a slim runtime image
Python: Install dependencies in the builder stage (pip install -r requirements.txt) and run with a minimal Python runtime
Go: Compile the binary in the builder stage and copy the static binary to a minimal distroless/static runtime
Java: Use Maven/Gradle in the builder stage to package a JAR, then run with a JRE runtime image
Static site: Build assets in the builder and serve with a minimal nginx or distroless image

Frequently Asked Questions

Add this skill to your agents