Multi-Platform Builds

A multi-platform build allows you to create a single Docker image that runs on different operating systems and CPU architectures, such as linux/amd64, linux/arm64, and windows/amd64. This ensures that your application can run seamlessly on various machines without modification.

Why Multi-Platform Builds?

Docker solves the "it works on my machine" problem by packaging applications and their dependencies into containers. However, containers share the host system’s kernel, meaning the container’s architecture must match the host. For example:

• A linux/amd64 container won’t run on an arm64 host without emulation.
• A Windows container won’t run on a Linux host.

Multi-platform builds address this by packaging multiple architecture-specific versions of an application into a single image, ensuring compatibility across different environments.

Single-Platform vs Multi-Platform Images

• Single-platform images contain one manifest, which defines the image’s configuration and layers.
• Multi-platform images contain a manifest list, which points to multiple manifests, each for a different platform. When pulling an image, Docker automatically selects the right variant for your system.

How Multi-Platform Images Work

When you push a multi-platform image to a registry, the registry stores:

• A manifest list, which acts as an index pointing to multiple manifests.
• Individual manifests, each with a configuration and layers specific to a platform.

When pulling the image, Docker selects the right variant for your machine. For example:

• On an ARM-based Raspberry Pi, Docker pulls the linux/arm64 image.
• On an x86-64 laptop, Docker pulls the linux/amd64 image.

Building Multi-Platform Images

Before building multi-platform images, ensure your Docker environment supports it. You have two main options:

• Enable the containerd image store (Required for multi-platform support as "classic" image store doesn't support it)
  • For Docker Desktop: Enable it in settings.
  • For Docker Engine: Modify the daemon configuration file.
• Use a custom builder with a driver that supports multi-platform builds (e.g., docker-container).
  • Allows building multi-platform images without switching to the containerd store.
  • However, images can only be pushed to a registry, not loaded into the local Docker Engine.

To create a custom builder, use the docker buildx create command to create a builder that uses the docker-container driver:

docker buildx create \
  --name container-builder \
  --driver docker-container \
  --bootstrap --use

The --bootstrap and --use initializes the builder instance and sets it as current active builder for the session.

To build images for multiple platforms, use docker buildx build command with --platform flag as shown below:

docker buildx build --platform linux/amd64,linux/arm64 -t myapp:1.0 .

If you want to specify a different builder instance explicitly, you can do so using builder option:

docker buildx build --builder container-builder --platform linux/amd64,linux/arm64 -t myapp:1.0 .