Colima Essentials

Colima Essentials

The Colima Essentials article provides you with a brief introduction to Colima. It provides an installation guide and command-line commands to set up a local container runtime on your machine (macOS, or Linux).

The Colima Essentials article provides you with a brief introduction to Colima. It provides an installation guide and command-line commands to set up a local container runtime on your machine (macOS, or Linux).

What is Colima?

Colima is a free container runtime available on macOS (and Linux) with minimul setup that can be used to provision the Docker container runtime in a Lima VM. Colima has a simple, easy to use command-line interface (CLI) and support both Intel and M1 processors. Other features of Colima includes, support for both docker and containerd runtimes, port forwarding, volume mounts, kubernetes and multiple instances.

Colima can be used as a replacement for Docker Desktop, especially since Docker Desktop is not free under certain conditions.

Docker Desktop is free to use, as part of the Docker Personal subscription, for individuals, non-commercial open source developers, students and educators, and small businesses of less than 250 employees. (Docker FAQ)

Lima launches Linux virtual machines with automatic file sharing, port forwarding and containerd. The purpose of Lima is to promote containerd including nerdctl to Mac users. Lima can also be used for non-container applications. Lima supports both qemu and vz of running guest machines, which can be specified only during instance creation.

Installation

Colima is available on Homebrew and can be installed on macOS with the following command:

# Install Colima using Homebrew
$ brew install colima

To install Colima making use of MacPorts, Nix, Arch, binaries, or building from the source, following the installation guideline on the official Colima Github page.

Since Colima can be used as an alternative for Docker Desktop, the following software is required:

$ brew install docker 
$ brew install docker-compose 
$ brew install docker-credential-helper
$ brew install kubectl    

Colima Configuration

Colima Default Configurations

There are two ways to edit the default configuration, the first is a one-off configuration by starting colima with the --edit flag, and the second is to edit the template for default configurations of new instances.

One-off Configuration

# One-off customisation of the default configuration before startup
$ colima start --edit

The config file is located at $HOME/.colima/default/colima.yaml and can be configured manually. The configurations for other profiles can be found at $HOME/.colima/<profile-name>/colima.yaml.

Template for Default Configuration

# Edit the template for default configurations of new instances.
$ colima template

The template file is located at $HOME/.colima/_templates/default.yaml.

Configure Docker Login

To ensure docker login is properly configured, you need to install docker-credential-helper. docker-credential-helpers is a suite of programs to use native stores to keep Docker credentials safe. You can use the following command to install docker-credential-helper on macOS if you have not already done this.

$ brew install docker-credential-helper    

A symlink is created in /usr/local/bin. To view the symlink and to ensure its configured correct, you can run the following command, and it should show something like:

$ ls -l /usr/local/bin/docker-credential-osxkeychain
/usr/local/bin/docker-credential-osxkeychain -> ../Cellar/docker-credential-helper/0.7.0/bin/docker-credential-osxkeychain    

The next step is to set the credstore property within the ~/.docker/config.json configuration file to the suffix of the program you want to use. For instance, set it to osxkeychain if you want to use docker-credential-osxkeychain. It may be set to something else like desktop.

After you have set the property, the configuration should look as follows:

{
  "credsStore": "osxkeychain"
}

Configure Docker Compose & Volume

To ensure docker compose is properly configured, create a cli-plugin folder by making use of the following command:

$ mkdir -p $HOME/.docker/cli-plugins
$ ln -sfn /usr/local/opt/docker-compose/bin/docker-compose $HOME/.docker/cli-plugins/docker-compose    

Verify Configuration

To ensure that Colima is succesfully installed and configured, the following commands can be used to verify the configuration. Start Colima with the specified container runtime, and run the status command on colima. After Colima was successfully started, run the docker version command to verify docker is working as the colima runtime. To ensure the credentials setup is working, run the docker login command. The docker-compose version command is used to verify Docker Compose is working.

$ colima start; colima status
$ docker version
$ docker login
$ docker-compose version

Colima Usage Scenarios

Basic Colima Usage

The basic usage scenario is to start the container runtime via colima. If this is the first time you use colima a new default profile is created with all the default configurations as per the template. If this is the first time you use docker, you should also log in to the Docker registry. The docker run command can be used to run any of the docker containers, in this case its based on the ‘hello-world’ docker image. Once you are done using docker, you should stop the docker runtime using the colima stop command. To ensure all instances of colima is stopped, run the colima list command.

The following are the default configurations to be allocated to the virtual machine:

# Number of CPUs to be allocated to the virtual machine.
cpu: 2
# Size of the disk in GiB to be allocated to the virtual machine.
disk: 60
# Size of the memory in GiB to be allocated to the virtual machine.
memory: 2
# Architecture of the virtual machine (x86_64, aarch64, host).
arch: host
# Container runtime to be used (docker, containerd).
runtime: docker
# Kubernetes configuration for the virtual machine.
kubernetes:
  enabled: false

The following commands is used to perform the basic usage of Colima:

# Start the default colima instance or create a new default
$ colima start

# List all of the Colima instances
$ colima status

# Log in to a Docker registry.
$ docker login

# Run the docker container called hello-world
$ docker run hello-world
 
# Stop the default colima instance 
$ colima stop

# List all instances of colima 
$ colima list

Manage Colima via Lima CLI

It is possible to manage the colima container runtime within the linux virtual machine via limactl in the event that the colima tool is not responding.

# List instances of linux virtual machines.
$ limactl ls

# Stop the Colima linux virtual machine.
$ limactl stop colima

# Delete the Colima linux virtual machine.
$ limactl delete colima

# Display help information about Lima
$ limactl --help

Colima Commands

The following commands is based on colima version 0.5.2. The intent of this section is not to replace the existing colima command documentation, but rather serve as a set of commands I regularly use.

Colima Command Overview

This section contains a list of colima commands with a set of examples:

  • colima completion - Generate completion script for different shells.
  • colima delete - Delete and teardown Colima and all settings.
  • colima help - Display help information about the different colima commands.
  • colima kubernetes - Manage Kubernetes cluster.
  • colima list - List all created instances.
  • colima nerdctl - Run nerdctl to interact with containerd. (Requires containerd runtime.)
  • colima ssh - Used to SSH into the VM, or appending additional command runs the command instead.
  • colima ssh-config - Show configuration of the SSH connection to the VM.
  • colima start - Start Colima with the specified container runtime and optional kubernetes.
  • colima status - Show the status of Colima.
  • colima stop - Stops Colima instance to free up resources. The state of the VM is persisted at stop.
  • colima template - Edit the template for default configurations of new instances.
  • colima version - Print the version of Colima.

Colima Command Examples

colima completion
Since I am making use of the Z shell (Zsh), I will only list those commands. The rest of the commands for the Bash, fish and PowerShell can be found within the help command.

# Display help information about the colima completion command for different shells.
$ colima completion --help

# Enable shell complation for the Z shell (Zsh).
$ echo "autoload -U compinit; compinit" >> ~/.zshrc

# Load the colima shell completion for every session. (Must Restart)
$ colima completion zsh > "${fpath[1]}/_colima"

colima delete
This command should be used with caution. The delete command deletes everything (configurations & Colima runtime). After the delete command, an initial startup of Colima is required when the start command is issued.

# Display help information for the colima delete command
$ colima delete --help

# Delete and teardown Colima and all settings.
$ colima delete

# Delete and teardown Colima and do not prompt for yes/no
$ colima delete -f

colima start
A new instance can be created during colima start by specifying the --profile flag.

# Display help information about the colima start command 
$ colima start --help

# Start Colima with the specified container runtime 
$ colima start

# Edit the configuration file before starting Colima  
$ colima start --edit

# Mount the $HOME directory, suffix ':w' for writable
$ colima start --mount $HOME:w

colima status
Show the status of Colima.

# Display help information about the colima status command 
$ colima status --help

# Show the status of Colima default instance 
$ colima status

# Show the status of the colima instance associated with profile called `my-profile`
$ colima stop --profile my-profile

colima stop
Stops the Colima instance and persist the state of the virtual machine. Starting the colima instance after stopping, should return it back to its previous state.

# Display help information about the colima stop command 
$ colima stop --help

# Stops Colima default instance to free up resources. 
$ colima stop

# Stop the colima instance associated with profile called `my-profile`
$ colima stop --profile my-profile

colima template
Edit the template for default configurations of new instances. The default editor is defined by the $EDITOR environment variable.

# Display help information about the colima template command 
$ colima template --help

# Edit the template for default configurations of new instances.  
$ colima template

# Editor to use for edit is Visual Studio Code (code)   
$ colima template --editor code

# Edit the configurations template associated with profile called `my-profile`
$ colima template --profile my-profile

Resources