CertGrid CertGrid

Dockerfile cheat sheet

Every Dockerfile instruction with what it actually does, plus the build flags worth remembering. Examples marked with a play button were executed on Ubuntu 26.04 with Docker 29.7.2 - nothing here shows output that was not captured.

Base image and stages

  • FROM image:tag

    Start a new build stage from a base image. Pin a real version - :latest is a moving target.

    Full guide
  • FROM image:tag AS name

    Name a stage so a later stage can COPY --from it.

    Full guide
  • FROM scratch

    An entirely empty base - no shell, no libc. Only viable for statically linked binaries.

    Full guide
  • FROM --platform=$BUILDPLATFORM image AS build

    Pin a stage to the machine doing the building so compilation stays native during a cross-platform build.

    Full guide

Files and filesystem

  • COPY src dest

    Copy from the build context into the image. Cannot reach outside the context.

    Full guide
  • COPY --from=stage src dest

    Copy from an earlier stage instead of the context. The basis of multi-stage builds.

    Full guide
  • COPY --chown=user:group src dest

    Set ownership as part of the copy, avoiding a separate chown layer.

    Full guide
  • ADD

    Like COPY but also expands local tar archives and fetches URLs. Prefer COPY unless you need those - ADD's extra behaviour surprises people.

  • WORKDIR /path

    Set the directory for later instructions and for the running container. Creates it if absent.

    Read it back with the single inspect in this section.

    Full guide
  • VOLUME /path Caution

    Declare a mount point. Docker creates an anonymous volume there at run time if nothing is mounted - which is easy to forget and leaves unnamed volumes behind.

    Full guide

Execution

  • RUN command

    Execute at BUILD time and commit the result as a layer. Clean up within the same RUN or the mess ships.

    Full guide
  • CMD ["exe","arg"]

    Default command at RUN time. Replaced entirely by anything you pass to docker run.

    Full guide
  • ENTRYPOINT ["exe"]

    The command that always runs. Arguments from docker run are appended to it rather than replacing it.

    Full guide
  • HEALTHCHECK CMD command

    Let Docker decide whether the container is healthy, rather than assuming Up means ready.

    Full guide
  • SHELL ["/bin/bash","-c"]

    Change the shell used by shell-form RUN, CMD and ENTRYPOINT.

Variables

  • ARG NAME=default

    Build-time only. Not present in the running container unless an ENV copies it.

    Full guide
  • ENV NAME=value

    Baked into the image and visible to the process. Overridable per container with -e.

    Full guide
  • ARG for secrets Whole-host

    Do not. Build args are recorded in the image history and readable by anyone with the image.

    Use BuildKit build secrets instead: RUN --mount=type=secret,id=mytoken. A secret passed as ARG survives in the image metadata even if the file is deleted in a later layer.

Identity and metadata

  • USER name

    Run later instructions and the container process as this account. The cheapest security improvement available.

    Read it back with the single inspect in this section.

    Full guide
  • EXPOSE 8080

    Metadata only. Documents an intended port and publishes nothing - you still need -p at run time.

    Read it back with the single inspect in this section.

    Full guide
  • LABEL key=value

    Attach metadata. Prefer the org.opencontainers.image.* keys so tooling can read them.

    Read it back with the single inspect in this section.

    Full guide
  • STOPSIGNAL SIGTERM

    Which signal stops the main process. Change it only if your process ignores the default.

  • docker image inspect IMAGE --format "user={{.Config.User}} ..."

    Read USER, ENV, EXPOSE and LABEL back off a built image in one command - which is how you check the Dockerfile did what you meant.

    Full guide

Build flags

  • docker build -t name:tag .

    Build from the Dockerfile in the context directory and tag the result.

    Full guide
  • docker build -f path/Dockerfile .

    Use a Dockerfile outside the context root. The context is still the final argument.

  • docker build --target stage .

    Build only up to a named stage. How you inspect an intermediate builder.

    Full guide
  • docker build --no-cache . Caution

    Ignore every cached layer. Slow on purpose - use to prove a build is reproducible.

    Full guide
  • docker build --progress=plain .

    Unfolded build log. Use it to see which layers were CACHED and which rebuilt.

    Full guide
  • docker buildx build --platform a,b --push .

    Build several architectures and push them as one manifest. Needs a docker-container builder.

    Full guide

Patterns worth memorising

  • Manifest first, then install, then source

    Keeps the dependency install cached across source changes. The single highest-value ordering rule.

    Full guide
  • .dockerignore at the context root

    Cuts what transfers and what lands in the image. Measured here at 3.00MB down to 138B.

    Full guide
  • Clean up inside the same RUN

    A file deleted in a later layer still ships in the layer that added it. apk add --no-cache and rm in the same RUN are the fix.

    Full guide
  • Build tools in a builder stage only

    Ship the artifact, not the compiler. 253MB of toolchain became a 112kB runtime image.

    Full guide
← Back to the Docker path