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
The colima completion command is used to set up command-line autocompletion for Colima commands in your shell. Autocompletion can save you time and reduce errors by suggesting possible commands and options as you type.
# Configures autocompletion for the Bash shell.
$ colima completion bash
# Configures autocompletion for the Zsh shell.
colima completion zsh
# Configures autocompletion for the Fish shell.
colima completion fish:
When you run the colima completion command with one of these options, it will output the code you need to add to your shell configuration file to enable autocompletion. You can copy and paste this code into your shell configuration file, save it, and then restart your shell to start using autocompletion with Colima commands.
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
The colima delete command deletes everything (configurations & Colima runtime). After the delete command, an initial startup of Colima is required when the start command is issued.. This command should be used with caution.
# 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 help
The colima help command is used to display the help menu for Colima. It provides an overview of all the available commands and options that you can use with Colima.
# Displays the help menu, which provides an overview of all the available commands and options.
$ colima help
# Displays detailed help information for a specific command.
$ colima help <command>
# Displays detailed help information for a specific command.
$ colima <command> --help
colima kubernetes
The colima kubernetes command is used to interact with a Kubernetes cluster running inside the Colima environment. Colima provides a lightweight and portable Kubernetes distribution that can be used for local development and testing.
# Delete the Kubernetes cluster
$ colima kubernetes delete
# Reset the Kubernetes cluster
$ colima kubernetes reset
# Start the Kubernetes cluster
$ colima kubernetes start
# Stop the Kubernetes cluster
$ colima kubernetes stop
colima start
The colima start command is used to start the specified container runtime and optional kubernetes. 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
