The Ultimate macOS Solution to Replace Docker Desktop: A Complete Guide to Colima + Proxy Configuration

Due to Docker Desktop's commercial licensing restrictions in corporate environments, many developers are forced to look for alternatives. Although Rancher Desktop is free, its experience is extremely poor on some machines (lag, high resource usage).

After comparing multiple options,Colima With its lightweight, blazing-fast, and 100% open-source and free features, it has become the best alternative on macOS. However, in certain network environments, getting Docker inside Colima to smoothly use the host (macOS) proxy is an extremely torturous pitfall.

This article will document the entire process from uninstalling Docker Desktop to completely resolving the Colima network proxy issue.

1. Uninstall Docker Desktop and Clean Up Residual Files

Use AppCleaner or delete directly /Applications/Docker.app It is often not enough; Docker will leave behind a large number of hidden files that take up space.

Thorough cleanup steps:

• Delete the application itself and any residual background processes.

• Clean up hidden virtual disks and configuration files (this is key to freeing up tens of GB of space):

sudo rm -rf ~/Library/Containers/com.docker.docker
sudo rm -rf ~/Library/Group\ Containers/group.com.docker
sudo rm -rf ~/.docker

II. Installation and Initialization of Colima

Install Colima and its related dependencies using Homebrew:

brew install colima docker docker-compose docker-buildx

Tip

On Intel-based Macs (such as the 2017 MBP), it is recommended to simply use the default startup; if it is an Apple Silicon (M1/M2/M3) chip, it is recommended to enable native virtualization.vz.

First startup (using a 4-core CPU and 6GB of memory as an example):

colima start --cpu 4 --memory 6

III. Pain Points: The Torture of Proxy Configuration in Network-Restricted Environments

After successful startup, try to pull the image:

docker run --rm hello-world

In certain network environments, you are likely to encounter the following two errors:

Error 1: DNS resolution failed (IPv6's fault)

dial tcp: lookup registry-1.docker.io on [::1]:53: read udp ...: connection refused

This is because the Docker daemon tries to use the IPv6 loopback to resolve the domain name, but it is blocked by a firewall or proxy software.

Error 2: configured host.docker.internal Still getting an error

proxyconnect tcp: dial tcp: lookup host.docker.internal on [::1]:53: read udp ...: connection refused

Many tutorials will tell you to write the proxy address as host.docker.internal(a dedicated domain name for virtual machines to access the host machine), but in actual testing under macOS + proxy software enhanced mode, this domain name is still incorrectly resolved to [::1] Lead to failure.

IV. The Ultimate Breakthrough: Lima's Underlying Proxy Injection Magic

After going through a round of solutions for fixing the LAN IP, I found that once the network environment changes (wired, wireless, etc.), the IP changes, so hardcoding the IP is completely unfeasible.

The real ultimate solution is: configure on the host machine 127.0.0.1, allowing Lima's underlying layer to automatically perform NAT translation.

1. Modify the Colima configuration file

Open the configuration file:

vim ~/.colima/default/colima.yaml

(It is recommended to run it once first colima start --edit( Ensure the file exists)

Focus on revising the following three places:

① Force external DNS (top-level configuration)

Move the DNS configuration to the outermost level of the file to override the default behavior:

dns:
  - 8.8.8.8
  - 223.5.5.5

② Disable IPv6 for the Docker daemon

Find docker: field, force disable IPv6 resolution:

docker:
  daemon.json:
    "ipv6": false

③ Inject host proxy environment variables

At the very bottom of the file env: field, just write the host machine's 127.0.0.1 and your proxy software's HTTP port (here, using Clash's default 7890 as an example):

env:
  HTTP_PROXY: http://127.0.0.1:7890
  HTTPS_PROXY: http://127.0.0.1:7890
  NO_PROXY: ::1,localhost,127.0.0.1,*.baidu.com,192.168.0.0/16,10.0.0.0/8

⚠️ Note

Please ensure the port number 7890 Consistent with the HTTP proxy port actually used by your proxy software. After testing, because Lima directly uses the NAT mechanism at the underlying level to forward local machine traffic,It takes effect without enabling "Allow LAN connections" in the proxy software..

2. Restart and apply

colima restart

V. Core Principle: Why Will It Succeed?

After configuration is complete, execute again docker run --rm hello-world, you will see the long-lost Hello from Docker!.

If you execute colima ssh Once you log in to the virtual machine, you will discover a very amazing phenomenon:

# View environment variables
env | grep -i proxy

# Output result:
https_proxy=http://192.168.5.2:7890
http_proxy=http://192.168.5.2:7890

You clearly configured it as 127.0.0.1, why did it become 192.168.5.2?

View the virtual machine's /etc/environment File, the truth is revealed:

cat /etc/environment

# Output result:
#LIMA-START
HTTPS_PROXY=http://192.168.5.2:7890
HTTP_PROXY=http://192.168.5.2:7890
NO_PROXY=kubernetes.docker.internal
#LIMA-END

This is the automatic injection mechanism of Lima (the underlying VM management tool of Colima):

• When you fill in 127.0.0.1 At that time, Lima knew that this was the host machine's local loopback address.

• Inside the virtual machine, Lima automatically replaces it with Default gateway address of the virtual network(i.e.192.168.5.2).

• Lima globally injects the converted environment variables into the virtual machine's system environment (/etc/environment) in.

Perfectly avoid pitfalls

Because a virtual network gateway is used (192.168.5.2), whether your Mac is at home, at work, or connected to a mobile hotspot,The gateway address never changes.. Completely solved the various problems caused by fixed IP, while also colima ssh after entering git,go and other command-line tools can also perfectly inherit this proxy setup.

Summary

At this point, you have a set of:

• Completely free, with no licensing restrictions. the container runtime environment.

• Extremely high performance(Based on macOS native vz framework or qemu).

• The network is working smoothly.(Supports global proxy penetration and is unaffected by changes in the network environment).

Uninstall the bulky Docker Desktop, embrace the lightweight Colima, and bring your Mac back to life!