Command-Line Docker Setup for macOS (without Docker Desktop)

This document outlines the steps to set up a complete Docker environment on macOS using only command-line tools. This provides an alternative to the paid Docker Desktop application, which is ideal for users who primarily interact with Docker through the terminal.

This setup uses Colima, a lightweight, open-source tool that provides container runtimes on macOS.

Prerequisites

• Homebrew package manager installed on your macOS.

Setup Process

The following steps will guide you through the installation and configuration of Colima and the necessary Docker tools.

1. Install Colima and Docker Tools

First, we install Colima, the Docker command-line interface (CLI), and Docker Compose using Homebrew.

brew install colima docker docker-compose

2. Start the Colima Virtual Machine

Colima runs the Docker engine inside a lightweight Linux virtual machine. Start the Colima VM with the following command. The first time you run this, it will download the necessary components and create the virtual machine.

colima start

3. Configure the Docker Context

By default, your Docker CLI might still be configured to look for a Docker Desktop installation. We need to tell it to use the engine provided by Colima. Docker manages this through "contexts".

Switch the active context to colima:

docker context use colima

4. Configure the Docker Compose Plugin

To ensure the docker-compose command works correctly as a Docker plugin, you need to update the Docker configuration file.

This command will create the ~/.docker/config.json file (if it doesn’t exist) and add the necessary setting.

mkdir -p ~/.docker && echo '{
  "cliPluginsExtraDirs": [
    "/opt/homebrew/lib/docker/cli-plugins"
  ]
}' > ~/.docker/config.json

Verification

To confirm that your setup is working correctly, run the hello-world container. This will download a small test image from Docker Hub and run it.

docker run hello-world

You should see a "Hello from Docker!" message, which confirms your environment is ready.

Daily Usage

Starting the Docker Environment

The Colima VM does not start automatically. When you want to use Docker, run:

colima start

Stopping the Docker Environment

When you are finished using Docker, you can stop the Colima VM to free up system resources:

colima stop

Uninstalling Docker Desktop

Once you have confirmed your Colima setup is working, you can remove the Docker Desktop application to free up space and avoid confusion.

Note: This command requires administrator privileges. You will need to run it in your own terminal and enter your password when prompted.

brew uninstall --cask docker

Troubleshooting

docker: command not found after uninstalling Docker Desktop

Uninstalling the Docker Desktop application can sometimes remove the docker command-line tool itself. If you see a "command not found" error, you can easily restore it.

Since the Docker CLI was also installed via Homebrew, you can re-link the formula to make the command available again:

brew link docker

After running this, the docker command should work correctly.