Colima Docker Setup

Colima Docker Setup

Set up Docker CLI + compose + buildx on macOS using Colima as the container runtime.

Quick Setup

Run the bundled setup script — it is idempotent:

bash <skill_dir>/scripts/setup.sh

This performs all steps: install, plugin symlinks, Colima start, verify.

Individual Steps

bash <skill_dir>/scripts/setup.sh install   # brew install colima docker docker-compose docker-buildx
bash <skill_dir>/scripts/setup.sh plugins   # symlink compose + buildx as docker CLI plugins
bash <skill_dir>/scripts/setup.sh colima    # create and start the default profile
bash <skill_dir>/scripts/setup.sh verify    # check everything works
bash <skill_dir>/scripts/setup.sh status    # alias for verify
bash <skill_dir>/scripts/setup.sh stop      # stop the Colima VM

Configuration via Environment Variables

Example with custom resources:

COLIMA_MEMORY=16 COLIMA_CPUS=8 bash <skill_dir>/scripts/setup.sh

Colima Default Template

To persist defaults across all future colima start invocations:

mkdir -p ~/.colima/_templates
cp <skill_dir>/assets/colima-template.yaml ~/.colima/_templates/default.yaml

Edit ~/.colima/_templates/default.yaml to customize. CLI flags override template values.

Key Facts

• vz + Rosetta (Apple Virtualization Framework) is required for performant x86_64 containers on ARM64 Macs. Without Rosetta, QEMU emulation is ~10x slower.
• docker compose (v2 plugin syntax with space) requires the compose binary symlinked into ~/.docker/cli-plugins/. The setup script handles this.
• DOCKER_HOST should be unix://$HOME/.colima/default/docker.sock — Colima sets this automatically when --activate is used.
• virtiofs is the fastest mount type with vz. $HOME is mounted writable by default.

Troubleshooting

Read <skill_dir>/references/troubleshooting.md for common issues: socket errors, missing compose plugin, slow x64 containers, VM startup failures, disk full, port conflicts.