How to Run Testcontainers with Colima on macOS with Apple M1 Chips

This article introduces how to run Testcontainers as an alternative after Docker Desktop became paid for some users.
Tags:

Docker changed the terms of service for Docker Desktop, so developers working at large companies can no longer use Docker Desktop for free. To use Docker for free on macOS, an alternative driver is needed. Several alternatives, such as hyperkit and VirtualBox, have been suggested, but they still do not seem easy to use on macOS with Apple M1 chips.

As of August 2023, the situation is as follows.

  • hyperkit: Does not work in an Apple M1 chip environment. Installation with Homebrew fails.
  • VirtualBox: The version that can run in an Apple M1 chip environment is still beta.

This article introduces the simplest way to run Testcontainers on Apple M1 with Colima, without using Docker Desktop.

Docker Setup

First, install Docker with Homebrew.

brew install docker

Colima Setup

Next, install Colima with Homebrew.

brew install colima

Then start Colima with the specified CPU and memory.

colima start --cpu 4 --memory 8

The command above runs the VM with 4 CPUs and 8 GiB of memory.

The Colima server becomes available at the following socket address.

unix:///Users/${HOME}/.colima/default/docker.sock.

You can connect to the Colima server with the Docker client.

You can check all contexts with the docker context ls command and switch to Colima with docker context use colima.

% docker context ls
NAME            DESCRIPTION                               DOCKER ENDPOINT                                  ERROR
colima *        colima                                    unix:///Users/user/.colima/default/docker.sock
default         Current DOCKER_HOST based configuration   unix:///var/run/docker.sock
desktop-linux                                             unix:///Users/user/.docker/run/docker.sock

To stop Colima, run the following command.

colima stop

Testcontainers Setup

Apple M1

If you use macOS on an Apple M1 chip, make sure that at least JNA (Java Native Access) version 5.7.0 or later is being used.

In IntelliJ IDEA, check whether the following library is included as a dependency.

JNA version

If the version is too low, update it to 5.7.0.

Testcontainers Environment Variables

To run Testcontainers with Colima, the following environment variables are required.

DOCKER_HOST=unix://${HOME}/.colima/default/docker.sock
TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock
TESTCONTAINERS_RYUK_DISABLED=true

These environment variables are needed for the following reasons.

  • DOCKER_HOST: Specifies Colima’s socket address.
  • TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE: Specifies the socket address inside the container.
  • TESTCONTAINERS_RYUK_DISABLED: Disables Ryuk. Otherwise, containers may not stop and tests may time out.

In a Bash or Zsh shell, you can override the Docker host by declaring the environment variables as follows.
~/.bashrc or ~/.zshrc

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

After changing the environment, restart IntelliJ IDEA so the changes are applied.