This blog post is the result of collaboration between Arm and Docker. Special thanks to Jason Andrews @ Arm for creating much of the original content.
Arm and Docker announced a strategic partnership earlier this year to unify software development and deployment across a diverse set of devices, from IoT endpoints to the edge of the network, and into the heart of the data center. Docker has simplified enterprise software development and deployment leading to true multi-platform portability and cost savings on Arm-based cloud instances. Even more exciting is how Docker is changing the way embedded software is being developed and deployed.
Traditionally embedded Linux software applications have been created by cross-compiling and copying files to an embedded target board. There are various methods to automate this process, but it has generally been unchanged since the 1990’s when non-x86 embedded possessors running Linux appeared. Docker stands to make the first significant change to the embedded Linux application developer’s workflow.
This article continues from Building Multi-Arch Images for Arm and x86 with Docker Desktop and shows the same capabilities in Linux. Although Windows and Mac support is great, the majority of software developers targeting embedded Linux systems also do their development work on Linux. The multi-architecture support in Docker also greatly simplifies embedded Linux application development and deployment.
If you are doing software development on x86 Linux machines and want to create Docker images that run on Arm servers or Arm embedded and IoT devices, this article will be helpful to understand the process and the different ways to do it.
Let’s see how to use Docker for Arm software development using the new buildx feature on Linux to create multi-architecture container images and run them. I’m using Ubuntu 18.04, but the same info applies to most any Linux distribution.
Install Docker
Installing Docker on Linux takes just a few commands. More installation info is available in the Docker Documentation.
If you already have an older version of Docker, make sure to uninstall it first. Using buildx requires Docker 19.03 and today the best way to get this is using the test instead of the stable version.
$ sudo apt-get update $ sudo apt-get upgrade $ curl -fsSL test.docker.com -o get-docker.sh && sh get-docker.sh
Add the current user to the docker group to avoid needing sudo to run the docker command:
$ sudo usermod -aG docker $USER
Make sure to log out and back in again. Now test the install with a quick hello-world run.
$ docker run hello-world
Hello from Docker!
This message shows that your installation appears to be working correctly.
To generate this message, Docker took the following steps:
1. The Docker client contacted the Docker daemon.
2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
(amd64)
3. The Docker daemon created a new container from that image which runs the
executable that produces the output you are currently reading.
4. The Docker daemon streamed that output to the Docker client, which sent it
to your terminal.
To try something more ambitious, you can run an Ubuntu container with:
$ docker run -it ubuntu bash
Share images, automate workflows, and more with a free Docker ID:
https://hub.docker.com/
For more examples and ideas, visit:
https://docs.docker.com/get-started/
Use the docker version command to check the running version:
$ docker version
Client:
Version: 19.03.0-beta4
API version: 1.40
Go version: go1.11.5
Git commit: d9934ea
Built: Tue May 14 06:46:47 2019
OS/Arch: linux/amd64
Experimental: false
Server:
Engine:
Version: 19.03.0-beta4
API version: 1.40 (minimum version 1.12)
Go version: go1.11.5
Git commit: d9934ea
Built: Tue May 14 06:44:59 2019
OS/Arch: linux/amd64
Experimental: false
containerd:
Version: 1.2.5
GitCommit: bb71b10fd8f58240ca47fbb579b9d1028eea7c84
runc:
Version: 1.0.0-rc6+dev
GitCommit: 2b18fe1d885ee5083ef9f0838fee39b62d653e30
docker-init:
Version: 0.18.0
GitCommit: fec3683
Install buildx for multi-architecture image builds
There are three options to get buildx on Linux:
- Use buildx directly from the test channel version of Docker
- Download a binary release of buildx and copy it to the $HOME/.docker directory
- Download, build, and install buildx from github.com
Use buildx from Docker test channel
The test version of Docker already has buildx included. The only thing needed is to set the environment variable to enable experimental command line features.
$ export DOCKER_CLI_EXPERIMENTAL=enabled
Download a binary release
Another way to get buildx is to download a binary release from github and put in the .docker/cli-plugins directory.
For example, download the buildx for Linux amd64 with a browser from: https://github.com/docker/buildx/releases/tag/v0.2.0
Then copy it to the cli-plugins/ directory (create it first if necessary):
$ cp buildx-v0.2.0.linux-amd64 ~/.docker/cli-plugins/docker-buildx
Download, build, and install buildx
Because buildx is a new command and documentation is still catching up, github is a good place to read more information about how buildx works.
To get buildx from github use the commands:
$ export DOCKER_BUILDKIT=1 $ docker build --platform=local -o . git://github.com/docker/buildx $ mkdir -p ~/.docker/cli-plugins $ mv buildx ~/.docker/cli-plugins/docker-buildx
To confirm buildx is now installed run the help and the version command.
$ docker buildx --help Usage: docker buildx COMMAND Build with BuildKit Management Commands: imagetools Commands to work on images in registry Commands: bake Build from a file build Start a build create Create a new builder instance inspect Inspect current builder instance ls List builder instances rm Remove a builder instance stop Stop builder instance use Set the current builder instance version Show buildx version information Run 'docker buildx COMMAND --help' for more information on a command. $ docker buildx version github.com/docker/buildx v0.2.0-36-g4e61674 4e61674ac805117794cc55475a62efdef0be9818
Register Arm executables to run on x64 machines
Install the qemu instruction emulation to register Arm executables to run on the x86 machine. For best results, the latest qemu image should be used. If an older qemu is used some application may not work correctly on the x86 hardware.
$ docker run --rm --privileged docker/binfmt:820fdd95a9972a5308930a2bdfb8573dd4447ad3
To verify the qemu handlers are registered properly, run the following and make sure the first line of the output is “enabled”. Note that the handler registration doesn’t survive a reboot, but could be added to the system start-up scripts.
$ cat /proc/sys/fs/binfmt_misc/qemu-aarch64 enabled interpreter /usr/bin/qemu-aarch64 flags: OCF offset 0 magic 7f454c460201010000000000000000000200b7
Create a multi-architecture build instance
Setup a new builder instance to create multi-architecture images.
$ docker buildx create --name mybuilder $ docker buildx use mybuilder $ docker buildx inspect --bootstrap Name: mybuilder Driver: docker-container Nodes: Name: mybuilder0 Endpoint: unix:///var/run/docker.sock Status: running Platforms: linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6
Try buildx
There are multiple examples of buildx available, but here is a simple one for C programmers! Create a file named hello.c with this code:
/* * hello.c */ #include <stdio.h> #include <stdlib.h> #ifndef ARCH #define ARCH "Undefined" #endif int main() { printf("Hello, my architecture is %s\n", ARCH); exit(0); }
Here is a Docker file to build and run it. Let’s get used to using multi-stage Docker files as it will be common for deploying embedded applications. Create a Dockerfile with the following:
# # Dockerfile # FROM alpine AS builder RUN apk add build-base WORKDIR /home COPY hello.c . RUN gcc "-DARCH=\"`uname -a`\"" hello.c -o hello FROM alpine WORKDIR /home COPY --from=builder /home/hello . ENTRYPOINT ["./hello"]
Now, use buildx to build for multiple architectures and push to Docker hub.
Use docker login first if needed and substitute your own Hub account.
$ docker buildx build --platform linux/arm,linux/arm64,linux/amd64 -t timtsai2018/hello . --push $ docker buildx imagetools inspect timtsai2018/hello Name: docker.io/timtsai2018/hello:latest MediaType: application/vnd.docker.distribution.manifest.list.v2+json Digest: sha256:6f2ad12a9400330107ca8ad1675ab2924ae18c61bc1d3c600fdf9e2212e3bb7a Manifests: Name: docker.io/timtsai2018/hello:latest@sha256:adcdcf8f511cb35f7cf124df3d339bf677a733ab40260e85945e0037cf02c598 MediaType: application/vnd.docker.distribution.manifest.v2+json Platform: linux/arm/v7 Name: docker.io/timtsai2018/hello:latest@sha256:3dc400e687a365aa5140718fde6cbbe37e050606f00274956e17fa9510df9573 MediaType: application/vnd.docker.distribution.manifest.v2+json Platform: linux/arm64 Name: docker.io/timtsai2018/hello:latest@sha256:9446cf48281105b4f41f1c697c1258e6d2f9b9389d1c0aa34e2209477ed720cb MediaType: application/vnd.docker.distribution.manifest.v2+json Platform: linux/amd64
Run using the sha from the manifest and see the output from uname as armv7l, aarch64, and x86_64:
$ docker run docker.io/timtsai2018/hello:latest@sha256:adcdcf8f511cb35f7cf124df3d339bf677a733ab40260e85945e0037cf02c598 Hello, my architecture is Linux buildkitsandbox 4.15.0-50-generic #54-Ubuntu SMP Mon May 6 18:46:08 UTC 2019 armv7l Linux $ docker run docker.io/timtsai2018/hello:latest@sha256:3dc400e687a365aa5140718fde6cbbe37e050606f00274956e17fa9510df9573 Hello, my architecture is Linux buildkitsandbox 4.15.0-50-generic #54-Ubuntu SMP Mon May 6 18:46:08 UTC 2019 aarch64 Linux $ docker run docker.io/timtsai2018/hello:latest@sha256:9446cf48281105b4f41f1c697c1258e6d2f9b9389d1c0aa34e2209477ed720cb Hello, my architecture is Linux buildkitsandbox 4.15.0-50-generic #54-Ubuntu SMP Mon May 6 18:46:08 UTC 2019 x86_64 Linux
Next steps
As we have seen, building multi-architecture containers can be created with buildx in the same way as with Docker Desktop for Mac and Windows. Give it a try for yourself and start making the transition to multi-architecture Docker images today.