Dockerfile Multi-stage Builds

wzdushu@gmail.com (wanzi) — Mon, 02 Jul 2018 16:22:42 +0800

Understanding Docker Multi-stage Builds:

Building an image requires a base image; all subsequent operations are based on this base image.
Docker image files have a layered structure. Each RUN instruction adds a new layer, so reducing the number of layers helps minimize image size.
When multiple FROM instructions are used, only the last FROM image becomes the root image of the final build.

Example of multi-stage build in my own project deployment: Here, we compile a binary using the Golang base image and then directly copy it into a minimal Alpine-based image:

FROM golang:1.12.7 as build
MAINTAINER wanzi <iwz2099@163.com>

# Compilation configuration
ARG NAME=gaia
ARG FLAGS=-tags=jsoniter
ARG GOOS=linux
ARG GOARCH=amd64
ARG PORT_TO_EXPOSE=10020

ENV GOPROXY https://mirrors.aliyun.com/goproxy/
ENV GO111MODULE on

WORKDIR /opt/gaia
COPY . .
RUN GOOS=$GOOS GOARCH=$GOARCH go build -mod vendor -ldflags="-s -w" -o $NAME $FLAGS

FROM alpine
WORKDIR /opt/gaia
COPY --from=build /opt/gaia/gaia .
RUN mkdir -p /opt/gaia/conf
VOLUME ["/opt/gaia/conf"]

CMD ["./gaia"]
EXPOSE $PORT_TO_EXPOSE

Detailed Dockerfile syntax

wzdushu@gmail.com (wanzi) — Thu, 21 Jun 2018 16:22:42 +0800

FROM

Specifies the base image used to build the Docker image. FROM must be the first non-comment instruction in a Dockerfile. If the specified image is not available locally, Docker will automatically pull it from the public registry.

Example:

`1`	`FROM ubuntu:14.04 # Inherits from ubuntu:14.04`

MAINTAINER

Specifies the maintainer information.

`1`	`MAINTAINER wanzi "iwz2099@163.com"`

ENV

Sets environment variables that are available for subsequent RUN instructions and persist at runtime within the container.

ENV <key> <value> — sets a single variable
ENV <key>=<value> ... — allows setting multiple variables at once

Example:

1
2

ENV LANG en_US.UTF-8
ENV LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8

RUN

Executes commands during image build time.

RUN <command>
RUN ["executable", "param1", "param2"]

Example:

1
2

RUN yum -y install bind-utils
RUN ["/bin/bash", "-c", "yum -y install bind-utils"]

The first form runs the command in a shell (/bin/sh -c), while the second uses exec execution. Use the second form to specify a different shell or interpreter.

Each RUN instruction executes a command on top of the current image layer, commits the result as a new layer, and subsequent RUN commands operate on the resulting image. Docker images are layered—any historical commit point can be used to create a new image, similar to version control in source code. Long commands can be split across lines using \.

COPY

Copies files or directories from the host filesystem into the container.

COPY <src> <dest>

Example:

`1`	`COPY script/ /build/script/`

Copies <src> (a relative path from the Dockerfile’s location) to <dest> inside the container. When copying local directories, prefer COPY over ADD.

ADD

Copies files or directories from the host filesystem into the container.

ADD <src> <dest>

Example:

1
2

ADD https://www.baidu.com/index.html   /var/www/html/
ADD ubuntu-xenial-core-cloudimg-amd64-root.tar.gz /

The <src> can be:

A relative path from the Dockerfile’s directory,
A URL (automatically downloaded and copied),
A local tar file (automatically extracted into a directory).

VOLUME

Declares a mount point for data volumes.

1
2

VOLUME [ "/data" ]
VOLUME [ "/var/lib/redis", "/var/log/redis" ]

Creates a mountable directory that can be mounted from the host or other containers. Typically used for databases or persistent data.

USER

Sets the user ID (UID) under which the container runs. This affects the user context for RUN commands.

USER <uid>

CMD

Supports three formats:

CMD ["executable","param1","param2"] — executes via exec, recommended.
CMD command param1 param2 — runs in /bin/sh, suitable for interactive applications.
CMD ["param1","param2"] — provides default parameters for ENTRYPOINT.

Specifies the default command to run when starting a container. Only one CMD instruction is allowed per Dockerfile; if multiple are defined, only the last one takes effect.

WORKDIR

Sets the working directory for RUN, CMD, and ENTRYPOINT instructions.

Example:

`1`	`WORKDIR /opt/nodeapp`

ONBUILD

Configures instructions to be executed when the built image is used as a base for another image.

ONBUILD [INSTRUCTION]

Example: A Dockerfile creating image-A contains:

1
2

ONBUILD ADD . /app/src
ONBUILD RUN /usr/local/bin/python-build --dir /app/src

When a new image is built using FROM image-A, these ONBUILD instructions are automatically added:

FROM image-A
# Automatically runs:
ADD . /app/src
RUN /usr/local/bin/python-build --dir /app/src

Images with ONBUILD are recommended to include this in their tag (e.g., ruby:1.9-onbuild).

ENTRYPOINT

Defines the default executable to run when the container starts. Unlike CMD, it cannot be overridden by command-line arguments unless explicitly changed via docker run --entrypoint.

Only one ENTRYPOINT instruction is allowed per Dockerfile; later ones override earlier ones.

Supported formats:

ENTRYPOINT [ "nodejs", "server.js" ]
ENTRYPOINT command param1 param2 — runs in shell

EXPOSE

Informs Docker that the container listens on a specific port at runtime.

EXPOSE <port>

When starting the container, use -P to let Docker assign a random port mapping automatically.

Example:

`1`	`EXPOSE 3000`

Notes & Best Practices

Keep the image minimal—avoid installing unnecessary packages.
Create a .dockerignore file to exclude unwanted files/directories (syntax similar to .gitignore).
Prefer official Docker Hub images as base layers to reduce image size.
Fix the initial instructions in the Dockerfile—avoid frequent changes to leverage caching effectively.
Use \ to join multiple RUN commands for better readability and maintainability.
Prefer COPY over ADD whenever possible.
Use the -t flag when building images for easier management.
Do not map public ports directly in the Dockerfile.
Always test the image locally before pushing it to a registry.

Dockerfile on Wanzi's Blog – Notes on life, tech, and DevOps.

Dockerfile Multi-stage Builds

Detailed Dockerfile syntax

FROM

MAINTAINER

ENV

RUN

COPY

ADD

VOLUME

USER

CMD

WORKDIR

ONBUILD

ENTRYPOINT

EXPOSE

Notes & Best Practices