Colima

date:

tags: containers docker macos linux

categories: Containers

updated: 2024-12-19

Colima is a tool that allows you to run container runtimes on macOS (and Linux) with minimal setup. If you are not familiar with containers and software such as Docker, check out a previous post to learn more.

It uses Lima, a lightweight virtual machine manager, to create and manage VMs that run Docker or containerd. If you have not worked with virtual machines before, I have an introductory post to explain the concept.

Installation

To install Colima, you can use Homebrew, a package manager for macOS. If you don’t have it, you can install it by following the instructions here. Once you have Homebrew, you can install Colima with this command:

1

brew install colima

Alternatively, you can use MacPorts, Nix, or other installation options as described on GitHub.

Starting Colima

To start Colima, you can use the colima start command with some optional flags. For example, you can specify the number of CPUs, memory, disk size, architecture, runtime, and Kubernetes options for your VM. Here are some examples of how to start Colima with different configurations:

  • Start Colima with the default settings (2 CPUs, 2 GB memory, 60 GB disk, Docker runtime):
1

colima start
  • Start Colima with 4 CPUs, 4 GB memory, 100 GB disk, and containerd runtime:
1

colima start —cpu 4 —memory 4 —disk 100 —runtime containerd
  • Start Colima with Rosetta 2 emulation (for M series Macs):
1

colima start —arch aarch64 —vm-type=vz —vz-rosetta

Optional Kubernetes

  • Start Colima with Kubernetes enabled and Traefik ingress controller:
1

colima start —kubernetes —kubernetes-ingress

You can see the full list of available flags by running colima start —help.

Using Colima

Once Colima is started, you can use the Docker or containerd CLI to interact with your containers. If you would like to know more about containerd, check out a previous post about alternatives to Docker for running containers.

Example: run a container in the CLI

For example, you can run the following commands in a terminal to pull and run a hello-world image:

1
2
3
4
5
6
7

# For Docker runtime
docker pull hello-world
docker run hello-world

# For containerd runtime
colima nerdctl pull docker.io/hello-world
colima nerdctl run docker.io/hello-world

containerd

Note that for nerdctl which is the containerd CLI, you need to specify docker.io/ as the domain for the container registry. This step can be skipped when using the docker CLI.

compose

You can also use Docker Compose to run multi-container applications. For example, you can create a docker-compose.yml file with the following content:

1
2
3
4
5
6
7
8
9

services:
  web:
    image: docker.io/nginx
    ports:
      - 8080:80
  db:
    image: docker.io/mysql
    environment:
      MYSQL_ROOT_PASSWORD: example

Then, you can run the following commands to start the services:

docker runtime

You need both docker and docker-compose on your system:

1

brew install docker docker-compose

I recommend linking the docker-compose binary to the docker plugins directory so we can just use it by entering docker compose up.

1
2
3
4

/*For Docker to find the plugin, add "cliPluginsExtraDirs" to ~/.docker/config.json:*/
  "cliPluginsExtraDirs": [
      "/opt/homebrew/lib/docker/cli-plugins"
  ]

Now when you have a compose file, you can bring it up using colima and docker commands:

1
2

# For Docker runtime
docker compose up -d

containerd runtime

1
2

# For Containerd runtime
colima nerdctl compose up -d

You can access the web service by visiting http://localhost:8080 in your browser.

Kubernetes

If you enabled Kubernetes, you can use kubectl to interact with your cluster. For example, you can run the following commands to get the cluster information and the nodes:

1
2

kubectl cluster-info
kubectl get nodes

If you are not familiar with Kubernetes, check out a previous post to get started and install the kubectl tool.

You can also deploy applications to your cluster using kubectl or helm. For example, you can run the following commands to install a WordPress application from the bitnami helm repo:

1
2
3
4
5
6

# Create a namespace for WordPress
kubectl create namespace wordpress

# Install WordPress using helm
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install wordpress bitnami/wordpress —namespace wordpress

You can access the WordPress service by visiting the URL shown in the helm output.

Stopping Colima

To stop Colima, you can use the colima stop command. This will stop the VM and free up the resources. You can also use the colima delete command to delete the VM and remove all the data. Note that this is irreversible, so make sure you backup any important data before deleting the VM.

Conclusion

Colima is a simple and powerful tool that lets you run container runtimes on macOS (and Linux) with minimal setup. It leverages Lima to create and manage VMs that run Docker or containerd. It also supports Kubernetes integration, so you can run a local cluster. Colima is a great alternative to Docker Desktop, especially for M series Mac users who want to run containers with Rosetta 2 emulation. Emulation allows you to run containers that are different CPU architectures. Most desktop computers still use x86_64/amd64 architecture.

comments powered by Disqus