Complete Guide to Installing Docker Engine on macOS via Homebrew

Evolution of Docker Installation Methods on macOS

The installation of Docker on macOS has evolved from traditional approaches to modern solutions. Early developers needed to use docker-machine with VirtualBox to create and manage Docker environments. While this approach provided full functionality, it involved relatively complex configuration and required additional virtual machine support.

Correct Method for Homebrew Docker Installation

When installing Docker through Homebrew, it's essential to use the --cask parameter to obtain the complete Docker for Mac application package. The correct installation command is:

brew install --cask docker

This command downloads and installs the complete Docker for Mac application, including the Docker engine, client tools, and necessary system components. After installation, you need to launch Docker.app from the Applications folder, and the system will prompt for necessary permissions.

Automatic Symbolic Link Creation Mechanism

When the Docker application is launched for the first time, the system automatically creates necessary symbolic links in the /usr/local/bin directory. These links include:

ls -l /usr/local/bin/docker*
lrwxr-xr-x  1 user  staff  67 /usr/local/bin/docker -> /Users/user/Library/Group Containers/group.com.docker/bin/docker
lrwxr-xr-x  1 user  staff  75 /usr/local/bin/docker-compose -> /Users/user/Library/Group Containers/group.com.docker/bin/docker-compose
lrwxr-xr-x  1 user  staff  90 /usr/local/bin/docker-credential-osxkeychain -> /Users/user/Library/Group Containers/group.com.docker/bin/docker-credential-osxkeychain
lrwxr-xr-x  1 user  staff  75 /usr/local/bin/docker-machine -> /Users/user/Library/Group Containers/group.com.docker/bin/docker-machine

These symbolic links ensure that command-line tools correctly point to the binaries provided by Docker for Mac.

Docker Running Status Verification

After installation, you can monitor Docker's running status through the Docker whale icon in the status bar. When the icon displays "Docker is running", it indicates that the Docker engine has successfully started and is operational. You can then verify the installation by running a test container:

docker run hello-world

This command downloads the hello-world image and runs a test container. The output should indicate that Docker installation and configuration are correct.

Version Information Check

Use the docker version command to view detailed version information, including client and server version numbers, API versions, etc. The correct output should display content similar to:

Client:
 Version:      17.03.1-ce
 API version:  1.27
 Go version:   go1.7.5
 Git commit:   c6d412e
 Built:        Tue Mar 28 00:40:02 2017
 OS/Arch:      darwin/amd64

Server:
 Version:      17.03.1-ce
 API version:  1.27 (minimum version 1.12)
 Go version:   go1.7.5
 Git commit:   c6d412e
 Built:        Fri Mar 24 00:00:50 2017
 OS/Arch:      linux/amd64
 Experimental: true

Comparison: Docker for Mac vs Traditional Installation

Docker for Mac utilizes lightweight virtualization technology based on xhyve, eliminating dependency on VirtualBox. This approach provides an experience closer to native Linux Docker, where services exposed by containers can be accessed directly through localhost, without the complex network mapping configurations required in traditional docker-machine approaches.

Common Issue Resolution

If the docker command is unavailable after installation, it's typically because the Docker application hasn't been launched for the first time. The solution is to launch Docker.app via Spotlight search, which will automatically create the necessary symbolic links. If installation fails due to permission issues, ensure you correctly enter the administrator password when prompted by the system.

Development Environment Configuration Recommendations

For development environments, it's recommended to use the complete solution provided by Docker for Mac, which integrates container runtime, network management, and volume storage functionalities, offering an out-of-the-box development experience. For scenarios requiring multi-environment management, consider combining docker-machine to manage remote or additional local environments.