Docker Syntax Buildkit

docker-syntax-buildkit

Quick Reference

Syntax Directive

ALWAYS include at the very top of every Dockerfile, before any other instruction:

# syntax=docker/dockerfile:1

This enables heredoc syntax, --mount flags, --chmod/--link/--parents/--exclude on COPY/ADD, the # check directive, and all other BuildKit extensions. ALWAYS use docker/dockerfile:1 (not 1.0 or a fixed minor version) to get the latest stable features.

Mount Types Overview

Platform ARGs (Automatic in BuildKit)

These ARGs are available automatically without explicit ARG declaration. ALWAYS declare them with ARG TARGETOS TARGETARCH inside a stage to use them in RUN instructions.

Critical Warnings

NEVER put secrets in ENV or ARG instructions -- they are visible in docker history and image layers. ALWAYS use --mount=type=secret instead.

NEVER omit the syntax directive when using BuildKit features -- without # syntax=docker/dockerfile:1, mount flags and heredoc syntax cause parse errors.

NEVER use sharing=shared (the default) for apt cache mounts -- apt requires exclusive access. ALWAYS use sharing=locked for apt caches.

NEVER assume secret mount contents trigger cache invalidation -- they do NOT. If a secret changes and the build must reflect that change, pass a CACHEBUST build arg.

ALWAYS use set -e in heredoc RUN blocks -- without it, individual command failures are silently ignored and the build continues.

Mount Type Decision Tree

Need to mount something during RUN?
|
+-- Persisting package downloads between builds?
|   --> type=cache (see Cache Mount Patterns below)
|
+-- Accessing credentials/tokens during build?
|   --> type=secret (file or env mode)
|
+-- Cloning private Git repos via SSH?
|   --> type=ssh
|
+-- Reading source files without creating a COPY layer?
|   +-- From build context? --> type=bind,target=.
|   +-- From another stage? --> type=bind,from=<stage>,target=<path>
|
+-- Need temporary scratch space (not persisted)?
    --> type=tmpfs

Heredoc Syntax

Multi-Line RUN

Run multi-line scripts without && chaining:

# syntax=docker/dockerfile:1

RUN <<EOF
#!/usr/bin/env bash
set -e
apt-get update
apt-get install -y --no-install-recommends curl git
rm -rf /var/lib/apt/lists/*
EOF

ALWAYS include set -e in heredoc RUN blocks. Without it, only the exit code of the LAST command determines success.

Inline File Creation

Create files without a separate COPY:

COPY <<EOF /etc/nginx/conf.d/default.conf
server {
    listen 80;
    server_name localhost;
    location / {
        root /usr/share/nginx/html;
    }
}
EOF

Multiple Heredocs

RUN <<INSTALL && <<CONFIGURE
apt-get update && apt-get install -y nginx
INSTALL
echo "daemon off;" >> /etc/nginx/nginx.conf
CONFIGURE

Cache Mount Patterns

ALWAYS use cache mounts for package managers. The cache is cumulative -- even when a layer rebuilds, only new/changed packages are downloaded.

See references/examples.md for complete patterns per package manager.

Cache Mount Full Syntax

--mount=type=cache,target=<path>[,id=<id>][,sharing=<shared|private|locked>][,from=<stage>][,source=<path>][,mode=<mode>][,uid=<uid>][,gid=<gid>]

Secret Mounts

As File (default)

RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
    aws s3 cp s3://bucket/file /dest

Build: docker build --secret id=aws,src=$HOME/.aws/credentials .

As Environment Variable

RUN --mount=type=secret,id=TOKEN,env=TOKEN \
    some-command  # $TOKEN is available

Build: docker build --secret id=TOKEN,src=./token.txt .

Secret Mount Options

SSH Mounts

RUN --mount=type=ssh \
    git clone git@github.com:org/private-repo.git /app

Build: docker build --ssh default .

ALWAYS add GitHub/GitLab host keys before cloning:

RUN --mount=type=ssh \
    mkdir -p ~/.ssh && ssh-keyscan github.com >> ~/.ssh/known_hosts \
    && git clone git@github.com:org/repo.git /app

Bind Mounts

# Mount entire build context (avoids COPY layer)
RUN --mount=type=bind,target=. go build -o /app/hello

# Mount from another stage
RUN --mount=type=bind,from=build,source=/src,target=/source ls /source

# Mount single file
RUN --mount=type=bind,source=requirements.txt,target=/tmp/requirements.txt \
    pip install -r /tmp/requirements.txt

Tmpfs Mounts

RUN --mount=type=tmpfs,target=/tmp gcc -o /app/binary source.c

Cross-Compilation Pattern

# syntax=docker/dockerfile:1

FROM --platform=$BUILDPLATFORM golang:1.22-alpine AS build
ARG TARGETOS TARGETARCH

WORKDIR /src
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download

COPY . .
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /bin/app ./cmd

FROM alpine:3.19
COPY --from=build /bin/app /usr/bin/app
ENTRYPOINT ["/usr/bin/app"]

Build multi-platform: docker buildx build --platform linux/amd64,linux/arm64 -t myapp:latest .

Cache Backends

Cache Modes

• min (default) -- Only caches exported layers. Smaller cache, fewer hits.
• max -- Caches ALL intermediate layers. Larger cache, more hits. ALWAYS use mode=max in CI/CD.

Registry Cache (CI/CD)

docker buildx build --push -t registry/app:latest \
  --cache-to type=registry,ref=registry/app:buildcache,mode=max \
  --cache-from type=registry,ref=registry/app:buildcache .

GitHub Actions Cache

docker buildx build \
  --cache-to type=gha,mode=max \
  --cache-from type=gha .

Reference Links

• references/mounts.md -- Complete reference for all 5 mount types with every option
• references/examples.md -- Cache mount patterns per package manager, secret patterns, SSH patterns
• references/anti-patterns.md -- BuildKit feature misuse and corrections

Official Sources

• https://docs.docker.com/reference/dockerfile/
• https://docs.docker.com/build/buildkit/
• https://docs.docker.com/build/cache/
• https://docs.docker.com/build/cache/backends/
• https://docs.docker.com/build/building/multi-stage/