Dockerfile Reference

Sets the base image for subsequent instructions. Every Dockerfile must start with FROM (except ARG before FROM). AS names a build stage for multi-stage builds.

FROM node:20-alpine AS builder
FROM nginx:1.25-alpine

Executes a command in a new layer on top of the current image and commits the result. Shell form uses /bin/sh -c. Exec form avoids shell processing.

Chain commands with && and clean up in the same layer to avoid bloat.

RUN apt-get update && apt-get install -y curl \
    && rm -rf /var/lib/apt/lists/*

Provides the default command when a container starts. Only the last CMD takes effect. Can be overridden at docker run. Not executed during build.

Prefer exec form over shell form for ENTRYPOINT+CMD patterns.

CMD ["node", "dist/index.js"]

Configures the container to run as an executable. CMD arguments are appended to ENTRYPOINT. Can be overridden with --entrypoint.

ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["postgres"]

Copies files from the build context into the image. Preferred over ADD for local files. Supports --chown and --from for multi-stage builds.

COPY --chown=node:node package*.json ./
COPY --from=builder /app/dist ./dist

Like COPY but also extracts local tar archives and fetches remote URLs. Use COPY unless you need these features.

Avoid for remote URLs — use RUN curl instead for better cache control.

ADD https://example.com/config.tar.gz /config/
ADD ./archive.tar.gz /app/

Sets environment variables that persist in the resulting image and are available to containers at runtime.

ENV NODE_ENV=production \
    PORT=3000 \
    LOG_LEVEL=info

Defines a build-time variable that can be passed with --build-arg. Unlike ENV, ARGs do not persist in the final image.

ARG values before FROM are not available after it — re-declare if needed.

ARG VERSION=latest
FROM node:${VERSION}-alpine
ARG BUILD_DATE
LABEL build.date=${BUILD_DATE}

Documents which network ports the container listens on at runtime. Does not actually publish the port — use -p at run time.

EXPOSE 3000
EXPOSE 8080/tcp
EXPOSE 5353/udp

Creates a mount point and marks it as a volume. Docker automatically creates an anonymous volume if none is specified at run time.

VOLUME ["/data", "/var/log/app"]

Sets the user (and optionally group) for subsequent RUN, CMD, and ENTRYPOINT instructions. Best practice: run containers as a non-root user.

RUN addgroup -g 1001 -S nodejs && adduser -S -u 1001 appuser
USER appuser

Sets the working directory for subsequent RUN, CMD, ENTRYPOINT, COPY, and ADD instructions. Creates the directory if it does not exist.

WORKDIR /app
COPY . .
RUN npm ci

Adds metadata to the image as key-value pairs. Standard OCI labels include org.opencontainers.image.title, version, revision.

LABEL org.opencontainers.image.title="My App" \
      org.opencontainers.image.version="1.0.0" \
      maintainer="team@example.com"

Tells Docker how to test if the container is still working. The container status becomes healthy or unhealthy based on the exit code.

HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

Overrides the default shell used for RUN, CMD, and ENTRYPOINT shell forms. Default is ["/bin/sh", "-c"] on Linux.

SHELL ["/bin/bash", "-o", "pipefail", "-c"]
RUN set -e && curl ... | sha256sum -c

Sets the system call signal to stop the container. Defaults to SIGTERM. Can be a signal name or number.

STOPSIGNAL SIGQUIT

Registers a trigger instruction to execute when the image is used as a base in another Dockerfile.

ONBUILD COPY . /app/src
ONBUILD RUN npm ci