Getting started
Introduction
A Dockerfile lists the instructions that build a container image; BuildKit, the default builder since Docker 23, runs them in parallel. This reference covers multi-stage builds, cache mounts, secrets, and the instructions you reach for most.
- Dockerfile reference (docs.docker.com)
- Build best practices (docs.docker.com)
First image
FROM node:24-alpine
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable pnpm && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]
Dependencies are installed before the source lands, so editing code skips the install layer.
See: Dockerfile reference
Build and run
docker build -t myapp .
docker run --rm -p 3000:3000 myapp
docker run --rm -it myapp sh
Common flags
| Flag | Effect |
|---|---|
-t name:tag | Name and tag the image |
-f path | Use another Dockerfile |
--build-arg KEY=value | Set a build-time ARG |
--target stage | Stop after a stage |
--platform linux/arm64 | Build for another architecture |
--no-cache | Ignore the layer cache |
--progress plain | Print full build output |
See: docker build
.dockerignore
node_modules
dist
.git
*.log
.env*
Everything in the build context is sent to the builder and can invalidate COPY layers, so keep the context small.
See: .dockerignore
Instructions
FROM
FROM node:24-alpine
FROM node:24-alpine AS build
FROM scratch
Pin a tag: latest moves under you. AS names a stage, and scratch starts an empty image for static binaries.
See: FROM
RUN
RUN apt-get update \
&& apt-get install -y --no-install-recommends curl \
&& rm -rf /var/lib/apt/lists/*
One RUN per logical step, with cleanup in the same command. A later RUN cannot shrink a layer an earlier one created.
See: RUN
COPY and ADD
COPY package.json pnpm-lock.yaml ./
COPY config.yml /app/
ADD https://example.com/file.tar.gz /tmp/
COPY is the default choice. ADD also unpacks local tarballs and fetches URLs, which is rarely what you want.
See: COPY
ENV and ARG
ARG NODE_ENV=production
ENV NODE_ENV=$NODE_ENV
ENV APP_HOME=/app
WORKDIR $APP_HOME
ARG exists only during the build and stays visible in image history, so never pass secrets that way. ENV persists into the container.
See: ARG
CMD and ENTRYPOINT
ENTRYPOINT ["node", "dist/server.js"]
CMD ["--port", "3000"]
Both use the exec form, so no shell wraps the process and signals reach it. CMD supplies default arguments that docker run can replace.
See: ENTRYPOINT
EXPOSE and USER
EXPOSE 3000
USER node
EXPOSE documents the port; publish it with -p. Set USER before CMD so the process does not run as root.
See: USER
HEALTHCHECK
HEALTHCHECK \
CMD curl -fsS http://localhost:3000/health || exit 1
Exit 0 means healthy and 1 unhealthy. --start-period=40s gives a slow boot time before failures count.
See: HEALTHCHECK
Multi-stage builds
Build and runtime
FROM node:24-alpine AS build
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable pnpm && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
FROM node:24-alpine
WORKDIR /app
COPY /app/dist ./dist
COPY /app/node_modules ./node_modules
USER node
CMD ["node", "dist/server.js"]
Only the last stage ships, so compilers, dev dependencies, and source stay out of the image.
See: Multi-stage builds
Copy from a stage
COPY /app/dist ./dist
COPY /app/static ./static
--from takes a stage name or an image, so you can lift a binary straight out of another image.
See: COPY --from
Target a stage
docker build --target build -t myapp:build .
Stopping at a stage is useful for debugging a failing build or for a CI image that runs tests.
BuildKit
Syntax directive
# syntax=docker/dockerfile:1
FROM alpine:3.22
The first line pulls the latest stable frontend, so new syntax works on an older daemon.
See: Dockerfile frontend
Cache mounts
RUN npm ci
A cache mount survives between builds even when the layer is invalidated, so only new packages download.
Cache paths
| Tool | Path |
|---|---|
| npm | /root/.npm |
| pnpm | /root/.local/share/pnpm/store |
| pip | /root/.cache/pip |
| Go | /go/pkg/mod |
| Cargo | /usr/local/cargo/registry |
| apt | /var/cache/apt and /var/lib/apt |
Apt needs sharing=locked, because concurrent builds must not touch the same index files.
See: Cache mounts
Bind mounts
RUN \
go build -o /app/hello
A bind mount reads the build context for one instruction without copying it into a layer. Writes are discarded when the step ends.
See: Bind mounts
Secrets
RUN \
npm ci
docker build --secret id=npmrc,src=$HOME/.npmrc .
The file is mounted for that one step only, so tokens never reach the image, the cache, or image history.
See: Build secrets
Best practices
Layer order
COPY package.json pnpm-lock.yaml ./
RUN corepack enable pnpm && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
Put rarely changing steps first. A source edit then rebuilds only the last two layers.
See: Cache optimization
Non-root user
Debian
RUN groupadd -r app && useradd -r -g app app
USER app
Alpine
RUN addgroup -S app && adduser -S app -G app
USER app
Containers run as root by default. Create an account, chown the directories it writes, and switch with USER before CMD.
See: Best practices
0 Comments for this cheatsheet. Write yours!