How to use Docker without Docker Desktop on MacOS 📦

Preamble

I think a lot of large software teams have struggled with Docker's licensing changes for Docker Desktop. I know it was a shock for me, starting at a company where my team was bigger than the whole organisation at my previous job. Docker Desktop's setup process is unrivaled in simplicity for configuring containers for most users.

The direction from my current company was to migrate to Podman, which don't get me wrong, it's okay and as a quick substitute for Docker Desktop works. However, I found it required a lot of tedious changes and extra setup and at the end of the day, I struggled to get AWS SAM to work which was my primary goal. It also didn't quite live up to the 'Docker replacement' I was told it would be.

It's important to note, the licensing changes only affect the Docker Desktop product, the CLI interface remains free for all users.

Instructions

The only prerequisite is Homebrew, which if you don't have installed, you can find instructions on their page here.

To kick things off, you'll want to install Docker and the credential helper. The credential helper allows you to use the macOS Keychain as the credential store for remote container repos instead of Docker Desktop.

brew install docker docker-credential-helper

You may come across an issue later on where the Docker CLI will throw an error that 'docker-credential-desktop not installed' which is a result of a misconfiguration (potentially from a previous installation of Docker Desktop). You can correct this by doing the following.

nano ~/.docker/config.json

{
        "auths": {},
        "credsStore": "osxkeychain",
        "currentContext": "colima"
}

Yours might not have the current context set to Colima yet, however, the important one to update is credStore.

Next, we need to install Colima. Colima is a container runtime that supports Docker (and containerd). You can read more about over on their GitHub.

brew install colima

Once this is installed, all you need to do is start the Colima VM.

colima start

Now you're good to go! You can test that everything is connected correctly by running. Where the * indicates the active context.

docker context ls
# this will return a list of docker socket configurations, example below

NAME       DESCRIPTION                               DOCKER ENDPOINT                                             KUBERNETES ENDPOINT                    ORCHESTRATOR
colima *   colima                                    unix:///Users/{you}/.colima/default/docker.sock                                          
default    Current DOCKER_HOST based configuration   unix:///var/run/docker.sock                                 https://192.168.64.3:16443 (default)   swarm

The solution for more stubborn apps

Despite us configuring everything, some applications (such as AWS SAM) try to attach directly to the Docker socket at /var/run/docker.sock instead of respecting the active configuration for the current context. As a result, we'll need to set up a hard symlink pointing the Colima socket to the expected Docker socket location.

# as /var/ is a protected directory, we will need sudo
sudo ln ~/.colima/default/docker.sock /var/run

# we can verify this has worked by running
ls /var/run
# and confirming that docker.sock is now in the directory

Once this link is established, you should be free to use those more stubborn applications. It's important to note that if you stop the Colima VM (container runtime), you may lose this symlink and you'll need to relink to continue using those apps.

I hope this has helped you set up Docker for your development setup and given you the most familiar experience (I mean, using the official Docker CLI is about as close as you can get right?).

Comments

[Roman Schwarz]

I am pretty new to Mac OS and never used Docker Desktop on Mac, instead jumped directly on an alternative to Docker Desktop. What I really like about Colima, that I can have multiple Docker (and Kubernetes) instances. This is handy when you are on an ARM processor (M1 e.g.) but need to build and run x86 containers. Colima allows me to spin up multiple instances with different platforms and configuration. Docker CLI allows to quickly jump between different Docker instances with docker context.

[Daniel Hillmann]

We had the same concern and discussion in the company i work. In the end I think a big reason for going with docker licensing was the fact that $5/mo is quickly spend in development hours if one have to fight their container setup every now and then.

[Elliot Alexander]

100%. It's definitely a far cleaner option, way easy to manage generally and for $5, it's fantastic all in one solution. I think in the case of the company I'm working at, containers don't play a huge part in our stack and most devs don't necessarily need them running at all times. As a result, $5 per users stacks up to a significant cost when most devs aren't using them day to day, so a relatively quick workaround like this can be super helpful.

[orliesaurus]

I don't really know how to do it - because I didn't look into it that much - but you can technically have docker run on a VPS and basically over SSH tunnel run everything on the VPS with code updates on git push or using rsync

That way your docker runs in a VPS, you have full access via SSH, and your laptop stays very cool and has an excellent battery life.

[Roman Schwarz]

Technically possible, but problematic with local volume mounts. This is the same when you run docker natively in a local VM. Colima, so Docker Desktop on Mac or Windows, closes this and other gaps very elegant.

[Roman Schwarz]

Did you try to use the env DOCKER_HOST instead of linking the docker.sock? Most tools consider this env, not sure about AWS SAM.

[Elliot Alexander]

That's a good point actually, I think I assumed Docker or Colima might update it to match the current context but maybe it's not. I did notice from some other tooling (LocalStack I think), that there appeared to be a python library for interacting with Docker that didn't seem to respect the active context. I will do some testing and report back :)