Multi-platform

Up until this point in the guide, you've built Linux binaries. This section describes how you can support other operating systems, and architectures, using multi-platform builds via emulation and cross-compilation.

The easiest way to get started with building for multiple platforms is using emulation. With emulation, you can build your app to multiple architectures without having to make any changes to your Dockerfile. All you need to do is to pass the --platform flag to the build command, specifying the OS and architecture you want to build for.

The following command builds the server image for the linux/arm/v7 platform:

$ docker build --target=server --platform=linux/arm/v7 .

You can also use emulation to produce outputs for multiple platforms at once. However, the default image store in Docker Engine doesn't support building and loading multi-platform images. You need to enable the containerd image store which supports concurrent multi-platform builds.

Enable the containerd image store

{
  "features": {
    "containerd-snapshotter": true
  }
}

$ systemctl restart docker

Build using emulation

To run multi-platform builds, invoke the docker build command, and pass it the same arguments as you did before. Only this time, also add a --platform flag specifying multiple architectures.

$ docker build \
    --target=binaries \
    --output=bin \
    --platform=linux/amd64,linux/arm64,linux/arm/v7 .

This command uses emulation to run the same build three times, once for each platform. The build results are exported to a bin directory.

bin
├── linux_amd64
│   ├── client
│   └── server
├── linux_arm64
│   ├── client
│   └── server
└── linux_arm_v7
    ├── client
    └── server

When you build for multiple platforms concurrently, BuildKit runs all of the build steps under emulation for each platform that you specify. Effectively forking the build into multiple concurrent processes.

There are, however, a few downsides to running multi-platform builds using emulation:

• If you tried running the command above, you may have noticed that it took a long time to finish. Emulation can be much slower than native execution for CPU-intensive tasks.
• Emulation only works when the architecture is supported by the base image you’re using. The example in this guide uses the Alpine Linux version of the golang image, which means you can only build Linux images this way, for a limited set of CPU architectures, without having to change the base image.

As an alternative to emulation, the next step explores cross-compilation. Cross-compiling makes multi-platform builds much faster and versatile.

Build using cross-compilation

Using cross-compilation means leveraging the capabilities of a compiler to build for multiple platforms, without the need for emulation.

The first thing you'll need to do is pinning the builder to use the node’s native architecture as the build platform. This is to prevent emulation. Then, from the node's native architecture, the builder cross-compiles the application to a number of other target platforms.

Platform build arguments

This approach involves using a few pre-defined build arguments that you have access to in your Docker builds: BUILDPLATFORM and TARGETPLATFORM (and derivatives, like TARGETOS). These build arguments reflect the values you pass to the --platform flag.

For example, if you invoke a build with --platform=linux/amd64, then the build arguments resolve to:

• TARGETPLATFORM=linux/amd64
• TARGETOS=linux
• TARGETARCH=amd64

When you pass more than one value to the platform flag, build stages that use the pre-defined platform arguments are forked automatically for each platform. This is in contrast to builds running under emulation, where the entire build pipeline runs per platform.

Update the Dockerfile

To build the app using the cross-compilation technique, update the Dockerfile as follows:

• Add --platform=$BUILDPLATFORM to the FROM instruction for the initial base stage, pinning the platform of the golang image to match the architecture of the host machine.
• Add ARG instructions for the Go compilation stages, making the TARGETOS and TARGETARCH build arguments available to the commands in this stage.
• Set the GOOS and GOARCH environment variables to the values of TARGETOS and TARGETARCH. The Go compiler uses these variables to do cross-compilation.

  # syntax=docker/dockerfile:1
  ARG GO_VERSION=1.21
  ARG GOLANGCI_LINT_VERSION=v1.52
- FROM golang:${GO_VERSION}-alpine AS base
+ FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-alpine AS base
  WORKDIR /src
  RUN --mount=type=cache,target=/go/pkg/mod \
      --mount=type=bind,source=go.mod,target=go.mod \
      --mount=type=bind,source=go.sum,target=go.sum \
      go mod download -x

  FROM base AS build-client
+ ARG TARGETOS
+ ARG TARGETARCH
  RUN --mount=type=cache,target=/go/pkg/mod \
      --mount=type=bind,target=. \
-     go build -o /bin/client ./cmd/client
+     GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o /bin/client ./cmd/client

  FROM base AS build-server
+ ARG TARGETOS
+ ARG TARGETARCH
  RUN --mount=type=cache,target=/go/pkg/mod \
      --mount=type=bind,target=. \
-     go build -o /bin/server ./cmd/server
+     GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o /bin/server ./cmd/server

  FROM scratch AS client
  COPY --from=build-client /bin/client /bin/
  ENTRYPOINT [ "/bin/client" ]

  FROM scratch AS server
  COPY --from=build-server /bin/server /bin/
  ENTRYPOINT [ "/bin/server" ]

  FROM scratch AS binaries
  COPY --from=build-client /bin/client /
  COPY --from=build-server /bin/server /

  FROM golangci/golangci-lint:${GOLANGCI_LINT_VERSION} as lint
  WORKDIR /test
  RUN --mount=type=bind,target=. \
      golangci-lint run

The only thing left to do now is to run the actual build. To run a multi-platform build, set the --platform option, and specify a CSV string of the OS and architectures that you want to build for. The following command illustrates how to build, and export, binaries for Mac (ARM64), Windows, and Linux:

$ docker build \
  --target=binaries \
  --output=bin \
  --platform=darwin/arm64,windows/amd64,linux/amd64 .

When the build finishes, you’ll find client and server binaries for all of the selected platforms in the bin directory:

bin
├── darwin_arm64
│   ├── client
│   └── server
├── linux_amd64
│   ├── client
│   └── server
└── windows_amd64
    ├── client
    └── server

Summary

This section has demonstrated how you can get started with multi-platform builds using emulation and cross-compilation.

Related information:

• Multi-platfom images
• containerd image store (Docker Desktop)
• containerd image store (Docker Engine)

You may also want to consider checking out xx - Dockerfile cross-compilation helpers. xx is a Docker image containing utility scripts that make cross-compiling with Docker builds easier.

Next steps

This section is the final part of the Build with Docker guide. The following page contains some pointers for where to go next.