The combination of Docker, Java, IntelliJ, and Testcontainers is very common in Java web/systems engineering. Testcontainers are used in common frameworks like Spring Boot and Quarkus. It’s somewhat accepted that integration testing with a DB configuration close to production is preferable to using an in-memory DB like h2 (as we did in the early 2000s).
I tried to replace Docker Desktop on macOS again and again for a very long time, because it just does not sit well with my CLI heavy workflow.
The Docker Desktop feature-set1 is huge, and it keeps growing. It works pretty well and it’s properly integrated. So well, they started charging for it:
Docker Desktop requires a paid, per-user subscription for organizations with more than 250 employees or more than $10 million in annual revenue per our terms of service. – Docker Desktop License Agreement
And I don’t want any of that - I want to use $ docker ps, $ dive my-little-image, $ lazydocker, $ k9s and $ minikube.
So I kept switching to different docker runtimes like podman and colima just to see that
- Docker contexts are still not properly supported by testcontainers-java
- it’s surprisingly complex to add Docker context support to testcontainers-java
- there’s no config to be found for Podman or colima where everything just works
- I have to revert back to Docker Desktop/OrbStack and accept the license fee for the 5% I use
But now I found a working setup in testcontainers-java#5034.
The Setup
First, we need to install colima and the lima guestagents.
The guestagents are technically not required but will help with an x86_64 VM on Apple Silicon.
You will see warnings on VM startup if that package is not installed.
The --network-address option with colima start is required for the ryuk resource reaper that Testcontainers manages.
$ brew install colima lima-additional-guestagents
$ colima start --network-address
$ colima list
PROFILE STATUS ARCH CPUS MEMORY DISK RUNTIME ADDRESS
default Running aarch64 2 2GiB 100GiB docker 192.168.106.9
Then we need to set DOCKER_HOST and additional environment variables for Testcontainers.
# ~/.zshrc
export DOCKER_HOST=unix://${HOME}/.config/colima/default/docker.sock
export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock
export TESTCONTAINERS_HOST_OVERRIDE=$(colima ls -j | jq -r '.address')
After sourcing .zshrc, the docker client is able to connect without switching the active context, because DOCKER_SOCKET wins.
Kind of an hack, but this will do until testcontainers-java will support Docker contexts (if ever).
$ source ~/.zshrc
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
$ docker context ls
NAME DESCRIPTION DOCKER ENDPOINT ERROR
colima colima unix:///Users/ra/.config/colima/default/docker.sock
default * Current DOCKER_HOST based configuration unix:///Users/ra/.config/colima/default/docker.sock
Warning: DOCKER_HOST environment variable overrides the active context. To use a context, either set the global --context flag, or unset DOCKER_HOST environment variable.
# run tests using testcontainers
$ mvn verify
[...]
2025-06-26 13:01:11,883 INFO [org.tes.doc.DockerClientProviderStrategy] (build-46) Found Docker environment with Environment variables, system properties and defaults. Resolved dockerHost=unix:///Users/ra/.config/colima/default/docker.sock
2025-06-26 13:01:11,884 INFO [org.tes.DockerClientFactory] (build-46) Docker host IP address is null
2025-06-26 13:01:11,894 INFO [org.tes.DockerClientFactory] (build-46) Connected to docker:
Server Version: 28.2.2
API Version: 1.50
Operating System: Ubuntu 24.04.1 LTS
Total Memory: 1959 MB
[...]
And IntelliJ picks up the environment variables automatically, because it does some magic bash/zsh integration.
Caveats
You need to source ~/.zshrc or (re)start IntelliJ after you do $ colima start.
But that can be remedied if you use the service included in the Homebrew formula:
$ brew info colima
[...]
==> Caveats
To start colima now and restart at login:
brew services start colima
[...]