---
name: docker-multi-stage-builder
description: "Scaffolds a production multi-stage Dockerfile for your language and package manager, with cached dependency installs, a slim runtime stage, a non-root user, and a health check, ready to build. Use when a new application needs a production multi-stage Dockerfile for its language and package manager with cached installs, a slim runtime, and a non-root user. Do not use for trimming an existing image to a size budget, debugging a running container, or writing Kubernetes or Compose files. Related topics: coding, devops, docker."
---

# Docker Multi-stage Builder

Scaffolds a production multi-stage Dockerfile for your language and package manager, with cached dependency installs, a slim runtime stage, a non-root user, and a health check, ready to build.

## When to use

Use this skill when a new application needs a production multi-stage Dockerfile for its language and package manager with cached installs, a slim runtime, and a non-root user. Do not use it for trimming an existing image to a size budget, debugging a running container, or writing Kubernetes or Compose files.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Define the dependency stage that copies only manifest and lock files and installs, so the layer caches until dependencies change.
3. Define the build stage that copies the source and produces the artefact, and choose the smallest runtime base that can run it.
4. Copy only artefacts and production dependencies into the runtime stage, pin every base image, and add the non-root user when requested.
5. Add EXPOSE, a HEALTHCHECK on the port, the exec-form start command, and the Development or Testing target when that environment is chosen.
6. Comment each stage with what it adds and what it leaves out, and give the docker build command with the target.

## Inputs

- **Language or platform** (choose one: Node.js, Go, Python, Java, Rust, Flutter Web, .NET, Ruby, PHP)
- **Package manager** (choose one: npm, yarn, pnpm, go mod, pip, poetry, uv, maven, gradle, cargo, bundler, composer)
- **Port to expose** (free text, e.g. "8080")
- **Start command** (free text, e.g. "node dist/server.js")
- **Use alpine or slim base images** (choose one: Yes, No)
- **Run as a non-root user** (choose one: Yes, No)
- **Environment** (choose one: Production, Development, Testing)
- **Native dependencies** (longer free text)

## Output

A single fenced Dockerfile block with commented stages (dependencies, build, runtime, plus a dev or test target when chosen), followed by the docker build command to use.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Docker Multi-stage Builder

Write a multi-stage Dockerfile for this application.

- Language or platform: {{Language or platform}}
- Package manager: {{Package manager}}
- Port to expose: {{Port to expose}}
- Start command: {{Start command}}
- Use alpine or slim base images: {{Use alpine or slim base images}}
- Run as a non-root user: {{Run as a non-root user}}
- Environment: {{Environment}}
- Native dependencies: {{Native dependencies}}

Lay out the stages for the toolchain of the chosen language: a dependency stage that copies only the manifest and lock file and installs, so the layer caches until dependencies change; a build stage that copies the source and compiles or bundles; and a runtime stage from the smallest base that can run the output (a static binary goes on scratch or distroless, interpreted languages on a slim image with only runtime packages). Copy only the build artefacts and production dependencies into the runtime stage. Pin every base image to a specific version tag. When non-root is on, create the user, chown only the paths the app writes, and switch before the CMD. Add EXPOSE, a HEALTHCHECK against the port, and the start command in exec form. For Development, add a target with the dev server and a bind-mount note; for Testing, add a stage that runs the test command and fails the build on failure. Comment each stage with what it contributes and what is deliberately left out of the final image, and finish with the docker build command including the target when more than one exists.

## Pitfalls

- Copying the whole source before installing dependencies, which rebuilds the install layer on every code change.
- Running npm install or pip install in the runtime stage, which drags the toolchain and dev dependencies back into the final image.
- Using the shell form of CMD, so signals never reach the process and graceful shutdown breaks.
