Home » Uncategorized » Switching from Docker Desktop to Colima on macOS

Switching from Docker Desktop to Colima on macOS

Posted on by

Docker Desktop free license does not allow using it for business purposes, one may find themselves needing an alternative – and, luckily, there is a proper one. There is Lima (Linux Machines, LiMa if you will) and Colima (Containers for Lima, essentially CoLiMa).

And license is not the only benefit – apparently Lima (and, consequently, Colima) should be noticeably faster than Docker Desktop. I cannot confirm this yet, but I’m eager to try.

The switch is quick, but will loose you all your local images – be aware!

Step 1 – delete Docker Desktop via Uninstall option in Troubleshooting section of Settings. (Honestly, I would have never guessed it myself that uninstallation is a part of troubleshooting – unless you uninstall to do clean install I guess).

Step 2 – install Colima and Docker via Homebrew: brew install docker && brew install colima

Step 3 (optionally) – Install Docker Compose via Homebrew, and follow the instructions it outputs to link it to Docker:
brew install docker-compose
and link via
mkdir -p ~/.docker/cli-plugins && ln -sfn $HOMEBREW_PREFIX/opt/docker-compose/bin/docker-compose ~/.docker/cli-plugins/docker-compose

Step 4 – switch Lima Virtual Machine type from Qemu to VZ – as the Lima documentation says, ““vz” option makes use of native virtualization support provided by macOS Virtualization.Framework”.

This is needed to get away from issues that Qemu VM has – which is a limit on write permissions, (which can be circumvented using this method, but is annoying), and a limit on file handles (that for me breaks PostgreSQL in Docker with “too many open files” error, and so far I have no answers on Colima discussion for this issue). If you don’t have those issues or can circumvent them – you may stay on Qemu. But it seems to only make sense for the case, when you need ARM image running on Intel host or vice versa – because this is the only serious macOS native virtualization limitation, apparently: “Virtualization.framework doesn’t support running “intel guest on arm” and vice versa” (as same documentation says, unless this other part of the documentation helps).

Anyhow, to change VM type one can either pass parameter --vm-type vz to the colima start command, or – better – add a line to the ~/.lima/_config/override.yaml file like this: vmType: "vz" (upd: apparently in newer versions it should be ~/.colima/_lima/_config/override.yaml – just copy the file there if it doesn’t exist)

P.S. Tried on macOS 14.0 (Sonoma), Intel Mac Book Pro 2018, Darwin Kernel Version 23.0.0: Fri Sep 15 14:42:42 PDT 2023; root:xnu-10002.1.13~1/RELEASE_X86_64 x86_64

P.P.S. Check for leftover ~/.docker/config.json – maybe it’s better to remove it before re-installing Docker. If you get error like this: error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH, out: `` – remove credStore from ~/.docker/config.json file.

P.P.P.S. If you get errors about docker.sock – try docker context use colima command, or, if it fails – set the environment variable DOCKER_HOST to unix://$HOME/.colima/docker.sock (e.g. export DOCKER_HOST="unix://$HOME/.colima/docker.sock").
Similar settings are required for Testcontainers – see https://www.rockyourcode.com/testcontainers-with-colima/

So in total I ended up with these in by .bashrc/.zshrc:

export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock
export DOCKER_HOST="unix://${HOME}/.colima/docker.sock"

References:

Leave a comment