5.3 Multi Stage Workflow

A multi-stage workflow is the overall pattern of organizing a Dockerfile into several distinct stages — each potentially with its own base image, dependencies, and purpose — using COPY --from to selectively carry forward only the specific artifacts each subsequent stage actually needs.

A Typical Multi-Stage Workflow

A common workflow separates a build stage (with full development tooling) from a final runtime stage (kept minimal), with only the compiled or bundled output crossing between them.

FROM node:20 AS build
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html

Extending the Workflow With a Dedicated Test Stage

A workflow can include additional stages serving purposes beyond just building and running, such as a dedicated stage for running tests, which need not be part of the final image at all.

FROM node:20 AS dependencies
COPY package*.json ./
RUN npm install

FROM dependencies AS test
COPY . .
RUN npm test

FROM dependencies AS build
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html

The test stage shares the dependencies stage's setup but exists purely to run tests during the build, never contributing anything to the final image.

Building Only a Specific Stage

A particular stage can be targeted directly, useful for running just the test stage without needing to also build the final production image.

docker build --target test -t myapp:test .

Why a Deliberate Multi-Stage Workflow Matters

Structuring a Dockerfile as a deliberate sequence of purpose-specific stages — rather than a single, monolithic sequence of instructions — supports better separation of concerns, smaller final images, and the ability to selectively build or test just one part of the overall workflow when that's all that's actually needed.