Setting Up Multi-Architecture Docker Builds with QEMU

Why Multi-Architecture Builds?

With the rise of ARM-based systems like Apple Silicon Macs and AWS Graviton instances, building container images for multiple architectures has become essential. This guide explains how to set up your Ubuntu system for multi-architecture Docker builds.

System Requirements

I'm assuming you're using a Debian or Debian derivate (Ubuntu, PopOS, Tuxedo OS, etc)

First, install the necessary virtualization packages:

sudo apt update && sudo apt install qemu-kvm qemu-system qemu-utils libvirt-daemon \
  libvirt-clients bridge-utils ovmf cpu-checker

sudo usermod -aG kvm $USER

These packages provide:

• QEMU: Hardware virtualization
• libvirt: API for virtualization
• bridge-utils: Network bridging tools
• OVMF: UEFI firmware for virtual machines
• cpu-checker: Verifies virtualization support

Setting Up Multi-Architecture Support

Docker needs QEMU to emulate different CPU architectures. Configure this with:

docker run --privileged --rm tonistiigi/binfmt --install arm64

This command installs the necessary binary format handlers for ARM64 architecture.

Creating a Multi-Architecture Builder

BuildKit, Docker's build system, needs a dedicated builder for multi-arch builds:

docker buildx create --name multiarch --driver docker-container --bootstrap
docker buildx use multiarch

Building Multi-Architecture Images

Build images for both AMD64 and ARM64 with:

docker buildx build --platform linux/amd64,linux/arm64 .

Best Practices

1. Test images on actual hardware when possible
2. Use multi-stage builds to optimize image size
3. Consider CI/CD pipeline integration for automated builds
4. Tag architecture-specific images alongside multi-arch manifests

Verification

Verify your setup with:

docker buildx ls

This should show your new builder with both platforms available.