How to Use Docker BuildKit for Faster Image Builds

How to Use Docker BuildKit for Faster Image Builds

BuildKit is Docker's next-generation build engine that provides significant performance improvements over the legacy builder. It offers parallel build stages, better caching, and advanced features that can cut build times dramatically on your Breeze server.

Enabling BuildKit

BuildKit is the default builder in Docker Engine 23.0+. For older versions, enable it explicitly:

# Enable for a single build
DOCKER_BUILDKIT=1 docker build -t myapp .

# Enable permanently in daemon.json
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "features": {
    "buildkit": true
  }
}
EOF
sudo systemctl restart docker

Key BuildKit Features

Parallel Stage Execution

BuildKit automatically runs independent stages in parallel:

FROM node:20-alpine AS frontend
WORKDIR /frontend
COPY frontend/package*.json ./
RUN npm ci
COPY frontend/ .
RUN npm run build

FROM golang:1.22-alpine AS backend
WORKDIR /backend
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o server

FROM alpine:3.19
COPY --from=frontend /frontend/dist /app/static
COPY --from=backend /backend/server /app/server
CMD ["/app/server"]

With BuildKit, the frontend and backend stages build simultaneously instead of sequentially.

Cache Mounts for Package Managers

Cache downloaded packages across builds to avoid re-downloading:

# Cache apt packages
RUN --mount=type=cache,target=/var/cache/apt \
    --mount=type=cache,target=/var/lib/apt \
    apt-get update && apt-get install -y build-essential

# Cache Go modules
RUN --mount=type=cache,target=/go/pkg/mod \
    go mod download

# Cache npm packages
RUN --mount=type=cache,target=/root/.npm \
    npm ci

# Cache pip packages
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

Secret Mounts

Pass secrets during build without embedding them in the image:

# In Dockerfile
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    npm ci

# Build command
docker build --secret id=npmrc,src=$HOME/.npmrc -t myapp .

SSH Agent Forwarding

Clone private repositories during build without copying SSH keys:

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

# Build command
docker build --ssh default -t myapp .

Inline Build Cache Export

Export and import build cache for CI/CD pipelines:

# Build and export cache to registry
docker build \
  --cache-to type=registry,ref=registry.yourdomain.com/myapp:buildcache \
  --cache-from type=registry,ref=registry.yourdomain.com/myapp:buildcache \
  -t myapp:latest .

Monitoring Build Performance

# Show detailed build timing
docker build --progress=plain -t myapp .

# View build history and sizes
docker history myapp:latest

Best Practices

• Always use cache mounts for package manager downloads
• Structure multi-stage builds so independent stages can run in parallel
• Use secret mounts instead of build args for sensitive values
• Export build cache in CI to speed up subsequent pipeline runs
• Use --progress=plain for debugging build issues on your Breeze server