Properly install Docker on macOS
TL;DR: You want to run
brew install --cask docker
to install Docker Desktop, not anything else. Read on for more information.
First I tried:
brew install docker docker-compose
and the command finished successfully. So I ran docker --version and docker-compose --version and both commands correctly displayed their respective version strings.
So I went inside a directory with a docker-compose.yml file and tried to start up the services with docker-compose up -d, but then Docker complained that it couldn’t find a daemon running. So I wasted twenty minutes checking if Homebrew had a service I could enable, or if there was some other way of starting the Docker daemon.
Turns out, the command brew install docker only installs the Docker client, not the server service required to actually run the Docker Engine and all the stuff underneath. That’s not available on macOS, because it’s not Linux, and doesn’t support all the containerization technology that Linux has, like cgroups and what not. The workaround that the Docker team came up with is to run a minimal version of Linux on a VM that the Docker client can communicate with.
So we need to run the following:
brew install docker-machine
brew install --cask virtualbox
to install the Docker Machine scripts and VirtualBox, which the Docker Machine scripts rely on. This requires a system reboot, because VirtualBox still uses kernel extensions. Um, okay, then. Time to save all my work and reboot.
Now we need to create a machine the Docker daemon can run on. So I ran:
docker-machine create --driver virtualbox default
But the command errored out after a while with a VBoxManage: error: Code E_ACCESSDENIED. So I dug deeper. It turns out that Docker Machine was deprecated sometime in September 2019, so we shouldn’t use it.
Okay, what then? Well, we use Docker Desktop, which is available as a Homebrew Cask and has (apparently) support for the new Apple Silicon-based Macs.
So we remove all the nonsense I did for the past couple of hours:
docker-machine rm default # press `y` to accept
rm -rf .docker # Be careful! Make sure there's nothing in .docker/ you wish to keep
brew uninstall docker-machine docker docker-compose virtualbox
And we now install the correct Docker Desktop Cask:
brew install --cask docker
So we got Docker working, right? Well, yes. But I really wanted to use just the Docker engine and not Docker Desktop, because Docker Desktop is proprietary and subject to license agreements with the corporation behind Docker. Only the Docker Engine is open-source and free to use, but it’s not available on macOS.
In the end, you’ll have to either use Docker Desktop on your macOS development machines, or set up another Linux instance that you can run Docker containers on.
Update: since writing this post I’ve come across the colima project, which aims to provide container runtimes on macOS through QEMU. It’s not perfect and still being actively developed and doesn’t have support for Apple Silicon Macs yet, which is why I won’t detail them here in this post. But it is definitely a project you should keep an eye on. I might switch to this once it matures.