A Complete Guide for Building Multi-Arch Docker Images

Imagine you've created a piece of software. You want it to run smoothly not just on your everyday laptop or desktop computer, but also on different types of devices, perhaps a tiny Raspberry Pi, a powerful cloud server, or even newer Mac computers. These different devices often use different types of main processors, also known as CPU architectures (like amd64/x86-64 for most PCs, or arm64 for many mobile devices, Raspberry Pis, and Apple Silicon Macs).

In the past, you might have needed to create and manage separate software packages for each type of computer. Now, multi-architecture (or multi-arch) Docker images can solve this problem. They allow you to build a single smart software package (a Docker image) that can automatically run on various CPU architectures and operating systems. You use one name to get the software, and Docker picks the right version for the computer it's on.

This is useful because:

• You manage one image tag for all platforms.
• Users automatically get the version optimized for their system.
• Your software can reach a wider range of hardware.

>> Explore further:

• Docker Networking Fundamentals: Types, Working and Usage
• How To Use Terraform for Provisioning A Docker Container?

What is a Docker Manifest List and How It Works?

A manifest list is a small file (in JSON format) that doesn't contain the software itself. Instead, it points to several different versions of your image, where each version is specifically built for a particular combination of CPU architecture and operating system (e.g., Linux on an amd64 chip, or Linux on an arm64 chip).

How it's used? When you try to run a multi-arch image (e.g., docker pull my-cool-app:latest), your Docker system first fetches this manifest list. It then checks its own architecture (e.g., "I'm an arm64 machine") and automatically downloads and runs the correct image variant from the list. The user doesn't need to specify their architecture; Docker handles it.

In short, the secret behind multi-arch Docker images is a manifest list (sometimes just called a "manifest"). You can think of it as a "smart table of contents" for your Docker image.

Dockerfile Basics for Building Multi Arch Docker Images

Every Docker image, including multi-arch ones, starts with a Dockerfile. This is a plain text file containing step-by-step instructions that Docker follows to assemble your software package.

Key instructions you'll often see:

• FROM: This specifies the base image – the starting point or foundation for your image. It could be a minimal operating system (like Alpine Linux or Ubuntu) or an image that already has a programming language environment (like Python or Node.js).
  • For multi-arch: It's crucial that your base image is also multi-arch. For instance, if you use FROM ubuntu:latest, Docker will automatically pull the Ubuntu base image version that matches the architecture you're currently building for. Alternatively, you can use build arguments to select different base images for different architectures if needed.
• RUN: Executes commands inside the image, such as installing software (RUN apt-get update && apt-get install -y my-tool) or setting up configurations.
• WORKDIR: Sets the main "working" folder inside the image for subsequent commands.
• COPY or ADD: Copies files or folders from your computer into the image (e.g., your application's code).
• CMD or ENTRYPOINT: Defines the default command that runs when a container is started from your image.

>> Read more: 

• How to Install Node.js on Ubuntu 22.04?
• A Comprehensive Guide To Dockerize A Golang Application
• How to Dockerize A Node.js Application & Deploy it To EC2?

How to Build Multi-Arch Docker Images?

There are primarily two ways to build multi-arch images. The modern approach using docker buildx is highly recommended for its simplicity and power. Besides, you can use the older way with docker manifest which can be a bit more complex. I'll guide you both.

Method 1: The Modern Way with docker buildx (Recommended)

Setting Up Your Build Environment

To build images for multiple platforms, especially if you're building for an architecture different from your own machine (e.g., building an ARM image on an x86 laptop), Docker needs a bit of setup:

1. Emulator (QEMU): Docker often uses an emulator called QEMU. This allows your computer to "pretend" it's a different architecture during the build process. Docker Desktop for Windows and Mac usually comes with QEMU pre-configured. For Linux, you might need to install QEMU static binaries and register them with the kernel's binfmt_misc handler. A common way to do this on Linux is by running a special Docker image: docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
2. Builder Configuration (docker buildx): Docker's extended build capabilities are provided by a component called BuildKit, accessed through the docker buildx command.

• Check existing builders: docker buildx ls. You'll see a list of builders. The default builder might not support multi-platform builds directly.
• Create a new builder (if needed): If you don't have a builder that supports multiple platforms (it will show the platforms it supports, like linux/amd64, linux/arm64, ...), you can create one:

docker buildx create --name mybuilder --use
    # This creates a new builder named 'mybuilder' and sets it as the current one.# You can bootstrap it to ensure it's running:
    docker buildx inspect --bootstrap

Docker Desktop users often have a suitable builder pre-configured.

Implementing docker buildx multiarch

docker buildx is a Docker CLI plugin that simplifies building for multiple platforms. It leverages BuildKit under the hood.

1. Ensure buildx and QEMU are ready (as described in the previous section).
2. Build and Push: Use a single docker buildx build command. The -platform flag specifies your target architectures (comma-separated). The -push flag tells buildx to build the image for all specified platforms and push them, along with the manifest list, directly to your container registry (like Docker Hub, GitLab Registry, etc.).

docker buildx build \
  --platform linux/amd64,linux/arm64,linux/arm/v7 \
  --tag your-username/your-image-name:latest \
  --push .

• -platform linux/amd64,linux/arm64,linux/arm/v7: Specifies the target platforms. Here, amd64 (common for PCs/servers), arm64 (for 64-bit ARM like Raspberry Pi 3/4, newer Macs), and arm/v7 (for 32-bit ARM like older Raspberry Pis).
• -tag your-username/your-image-name:latest: The name and tag for your image.
• -push: Pushes the resulting images and manifest list to the registry.
• .: Specifies that the Dockerfile is in the current directory.

If you want to build and load the image into your local Docker daemon for the native architecture only (while still building for multiple platforms if they were pushed), you can use --load. However, for true multi-arch deployment, --push is essential.

Method 2: The Older Way with docker manifest (More Complex)

This method is more manual and generally not recommended for new workflows, but it's good to understand the underlying mechanics. docker buildx automates these steps.

Steps:

1. Build for Each Architecture Separately: You would build an image for each target platform, tagging them distinctively. For example:

# Build for AMD64
docker buildx build --platform linux/amd64 -t your-username/my-app:amd64-latest --load .
# Build for ARM64
docker buildx build --platform linux/arm64 -t your-username/my-app:arm64-latest --load .

(Using --load here to get them into the local Docker image store, assuming you have a way to build for that platform, or using separate machines/builders for each).

• Push Each Architecture-Specific Image:

docker push your-username/my-app:amd64-latest
docker push your-username/my-app:arm64-latest

• Create the Manifest List: Use the docker manifest create command to create a manifest list that points to your architecture-specific images.

docker manifest create your-username/my-app:latest \
    --amend your-username/my-app:amd64-latest \
    --amend your-username/my-app:arm64-latest

• Annotate the Manifest (Optional but Recommended): You can provide more details about each image in the manifest.

docker manifest annotate your-username/my-app:latest your-username/my-app:amd64-latest --os linux --arch amd64
docker manifest annotate your-username/my-app:latest your-username/my-app:arm64-latest --os linux --arch arm64

• Push the Manifest List:

docker manifest push your-username/my-app:latest

As you can see, docker buildx with the --push flag handles all of this complexity in a single command.

Best Practices for Multi-Arch Images

• Use Multi-Arch Base Images: Always start your Dockerfile with a base image that itself supports multiple architectures (e.g., FROM debian:bullseye-slim, FROM alpine:latest). Most official images on Docker Hub are multi-arch.
• Test on Target Architectures: While QEMU emulation is good for building, always test your images on actual hardware of the target architecture if possible, especially for performance-sensitive applications.
• Consider Build Times: Building for multiple architectures, especially with emulation, can take longer. Optimize your Dockerfile for layer caching.
• Automate with CI/CD: Integrate your multi-arch builds into your Continuous Integration/Continuous Deployment (CI/CD) pipelines (e.g., GitHub Actions, GitLab CI). Many CI platforms provide native support or easy ways to configure docker buildx and QEMU.

Conclusion

Docker multi-arch images are a powerful feature that simplifies software distribution across diverse hardware. By using tools like docker buildx and following best practices, you can ensure your applications are easily accessible and performant for users on a wide array of platforms, all while managing a single, convenient image tag. This "build once, run anywhere (on supported architectures)" approach is a cornerstone of modern, efficient software deployment.

>>> Follow and Contact Relia Software for more information!