Quick Introduction to Docker Multi-Architecture Images
Multi-architecture images are an excellent tool, especially when deploying applications in environments with different architectures. Despite the dominance of the x86 architecture, ARM processors are gaining popularity, and RISC-V devices are also emerging. Since these architectures are not compatible with each other, there is an issue when trying to run images created for one architecture on devices with a different architecture. For example, an image built on a computer with an x86 processor will not work on a Raspberry Pi with an ARM processor. A common solution is to rebuild the image on the target device, but this is neither convenient nor optimal. This is where multi-architecture images come into play. Docker provides a tool for building such images. The process involves simultaneously creating images in separate emulators for each architecture, and in the end, Docker merges them into one unified image. Thanks to this, we get a single universal image that can be deployed on devices with different processor architectures.
Where to Start?
The first step should be to check if the base image supports the architectures you're interested in. The easiest way to do this is on DockerHub. In the image tag list, you’ll find information about the supported architectures.
Sample Project
The next step is the project you want to run. In our example, it is a simple PHP script.
<?php declare(strict_types=1);
$date = new DateTime();
$date->modify('+1 day');
echo 'Tomorrow will be: ' . $date->format('H:i:s d.m.Y') . ' // LASEROVSKY.NET';
For such a simple PHP script, the Dockerfile is also very simple and is based on the official PHP image.
FROM php:8.3.11-alpine
COPY ./script.php script.php
CMD ["php", "script.php"]
The standard way to run this project would be:
docker build --tag laserovsky/docker-multiarch-example:single-arch .
docker run laserovsky/docker-multiarch-example:single-arch
However, this image is built only for the architecture of the machine it was created on — in this case, x86.
buildx
The solution to this problem is buildx, which is part of Docker. With buildx, you can create a multi-architecture builder. To do this, simply run the following command once:
docker buildx create --use
From this point on, you can build multi-architecture images. Unfortunately, images built this way will not appear in your local image list. Therefore, you cannot run them as shown in the previous example. The best way to solve this is by logging into a Docker registry (by default DockerHub, but you can use any other registry) and building the image with buildx using the --push flag. Once the build is complete, the image will be pushed to the registry, from where it can be run on any operating system.
docker login
To build the above project for x86, ARM, and RISC-V architectures, simply run:
docker buildx build --push --platform linux/amd64,linux/arm64/v8,linux/riscv64 --tag laserovsky/docker-multiarch-example:multi-arch .
docker run laserovsky/docker-multiarch-example:multi-arch
The image you create can be run on your x86 computer, Raspberry Pi on ARM, and MangoPi on RISC-V. Multi-architecture images can be built for any number of architectures, as long as the base image supports them.
Summary
Building multi-architecture images is a powerful tool that allows you to deploy applications across different platforms without the need to adjust images for each of them. With Docker and its tools, like buildx, this process is easier than ever. I hope this guide has helped you understand how to start building such images and how to use them in your projects. The image created during the writing of this article is available for testing here.
Thank you for reading! If you want to learn more about containerization, Docker, or other technologies, feel free to check out the other articles on the blog.