docker / buildx

Buildx Workflow - docker/buildx

Buildx Workflow

This document covers the common commands, processes, and workflows for using buildx for building Docker images. The following sections will discuss the possible options and provide examples for each option.

Environment Variables for Docker Build

buildx supports various environment variables that affect the behavior of building features. Here are some of them:

  • BUILDKIT_COLORS: configure text color for the terminal output.
  • BUILDKIT_HOST: specify host to use for remote builders.
  • BUILDKIT_PROGRESS: configure type of progress output.
  • BUILDX_BUILDER: specify the builder instance to use.
  • BUILDX_CONFIG: specify location for configuration, state, and logs.
  • BUILDX_EXPERIMENTAL: turn on experimental features.
  • BUILDX_GIT_CHECK_DIRTY: enable dirty Git checkout detection.
  • BUILDX_GIT_INFO: remove Git information in provenance attestations.
  • BUILDX_GIT_LABELS: add Git provenance labels to images.
  • BUILDX_NO_DEFAULT_ATTESTATIONS: turn off default provenance attestations.
  • BUILDX_NO_DEFAULT_LOAD: turn off loading images to image store by default.

For more information, see Environment variables for Docker Build.

Building Multi-Arch Images for Arm and x86 with Docker Desktop

buildx allows you to build multi-arch images locally and soon remotely. It adds new builder instances based on BuildKit and leverages Docker Desktop technology stack to run non-native binaries.

Here’s an example of building a multi-arch image:

docker buildx build --platform linux/amd64,linux/arm64 -t myimage:latest .

For more information, see Building Multi-Arch Images for Arm and x86 with Docker Desktop.

docker buildx build

docker buildx build is the command to build images with buildx. Here are some of the options:

  • --progress: set type of progress output (auto, plain, tty).
  • --provenance: shorthand for --attest=type=provenance.
  • --pull: always attempt to pull all referenced images.
  • --push: shorthand for --output=type=registry.
  • --quiet: suppress the build output and print image ID on success.
  • --rm: remove intermediate containers after a successful build.
  • --file: name of the Dockerfile.
  • --platform: set target platform for build.
  • --output: output destination.

For more information, see docker buildx build.

Configuring your GitHub Actions builder

buildx supports running builds on multiple machines, which is useful for building multi-platform images on native nodes for more complicated cases that aren’t handled by QEMU.

Here’s an example of configuring a GitHub Actions builder:

# .github/buildkitd.toml
[worker.oci]
max-parallelism = 4
name = "ci"

For more information, see Configuring your GitHub Actions builder.

docker buildx

docker buildx is the command to install and manage buildx. Here are some of the options:

  • --builder: override the configured builder instance.
  • --driver: specify the driver to use for the builder.
  • --help: print usage information.

For more information, see docker buildx.

Publishing with Github Actions

buildx supports publishing images with Github Actions. Here’s an example of a Github Actions workflow:

name: Package, Publish, and Register
on:
push:
branches:
- main
jobs:
register:
name: Package, Publish, and Register
runs-on: ubuntu-latest
steps:
- id: checkout
uses: actions/checkout@v3
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Login to GitHub Container Registry
uses: docker/login-action@v2
with:
registry: ghcr.io
username: ${{ github.repository_owner }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Build and Publish
run: |
docker buildx build --platform linux/amd64,linux/arm64 -t ${{ github.repository_owner }}/myimage:latest . --push

For more information, see Publishing with Github Actions.

Buildx Workflow Example

Here’s an example of a complete buildx workflow:

# Configure buildx
export BUILDX_CONFIG=/usr/local/etc
export BUILDX_EXPERIMENTAL=1

# Create a builder
docker buildx create --name mybuilder --driver docker-container

# Build and publish a multi-arch image
docker buildx build --platform linux/amd64,linux/arm64 -t myimage:latest . --push

# Clean up
docker buildx rm mybuilder

For more information, see Buildx Workflow.