How to build Intel Docker containers on Mac M1

Lima is a tool that is very often described as the containerd for Mac. With it you can run a linux operating system alongside your Mac. It features automatic port forwarding, seemless file sharing, and supports various linux distributions such as AlmaLinux, Alphine, Arch Linux, Debian, Fedora, SUSE, Oracle Linux, Rocky and Ubuntu. By default it comes with containerd and nerdctl, but you can use Lima for non-container tasks as well.

Mac computers with Apple sillicon

Late 2020 Mac released their first systems with Apple Silicon, a custom designed Arm-based chip for Mac. The most recent editions of the Macbook pro uses the M1 Apple Silicon processor, whereas it used to be an Intel processor. Their new custom chipset is unable to process Intel instructions without the aid of additional software. Applications that have been built for Intel can still be used on a Mac with the use of emulation software that Apple has made available: "Rosetta 2".

The Rosetta 2 software, however, has some limitations as to what it can process. In particular it's often incompatible with virtual machine applications, which brings us to the next topic: Docker.

Challenges with Docker using the new M1 processor

A significant portion of developers use Docker for their local development work. By default Docker does support emulating amd64 by specifying the --platform linux/amd64 flag for building and running containers. Most images and packages are available for amd64, but not every package has transitioned. I recently had a use case where I absolutely needed an Intel architecture for a container. The options I had were either building the image on my old Macbook, or spin up a virtual machine with the correct architecture.

Setting up Lima to build docker images

And in comes Lima. My goal was to set up an environment in which I could build Docker containers as I was used to, without having to transfer files to another system or resort to my old Macbook. Lima is the perfect tool to do so.

You can install lima on MacOS using brew: brew install lima. Once it's installed: limactl start and choose:

Open an editor to review or modify the current configuration

On the line where it says arch: null replace null with x86_64. By default it will use the architecture of your operating system (in the case of an M1 it's aarch64). After you save the configuration file, type the following commands:

limactl shell default
sudo systemctl start containerd
sudo nerdctl run --privileged --rm tonistiigi/binfmt --install all
exit

This is required for the guest OS to be able to execute non-native binaries. And that's it for installation! Lima comes with containerd and nerdctl for building docker images.

Creating an alias to make building Docker images with Lima easy

The method of building Docker containers is normally as follows: lima nerdctl build ., where lima nerdctl is a drop-in replacement for the docker command. To keep my current way of working, I've added an alias:

alias docker='lima nerdctl'

Type:

echo alias docker=\'lima nerdctl\' >> ~/.zprofile to make this alias persistent. Now you can use the docker command as usual, but build and run images using an emulated Intel processor. You can change the name of the alias (e.g. dockerr) if you want to keep being able to use your native architecture to build images.

When you run a docker image through lima, port forwarding is automatically arranged, so any port your container listens on is exposed on localhost. In addition, you can create several lima instances and use them concurrently. The limactl start command has an optional argument: limactl start foobar will create a lima instance called foobar, and with LIMA_INSTANCE=foobar lima [command] you can execute commands on that specific instance.

Drawbacks

By default your Mac home directory is read only. This is intentional. Write support on Mac home directories is experimental. You can yolo it by editing the ~/.lima/default/lima.yaml file and set writable to true and restart lima (limactl stop && limactl start). Having said that, the lima home directory is writable, so if you simply place your code there it negates the need to make the Mac home directory writable.

Another drawback is the speed. Especially if you're compiling stuff in your container you really notice the difference between a native architecture and an emulated one. Unfortunately that is not to change any time soon.