A complete one-by-one guide to install Docker on your Mac OS using Homebrew

Beginner’s guide to install and run Docker on Mac OS

(update 2021–01–10)NOTE:
Some kind reader reported me that this seems not working for Mac with Apple silicon M1. I am sorry but I am not going to inspect in a short period. For M1 user, please look for other resources.

Configurations

System Version: macOS 10.14.3 (18D109)
Kernel Version: Darwin 18.2.0
Shell: zsh
Package manager: Homebrew

TL;DR

For short, the entire installation process is as follows.

$ brew install docker docker-machine
$ brew cask install virtualbox
-> need password
-> possibly need to address System Preference setting
$ docker-machine create --driver virtualbox default
$ docker-machine env default
$ eval "$(docker-machine env default)"
$ docker run hello-world
$ docker-machine stop default

Docker installation using Homebrew

Step-by-step Installation Process

Docker installation via Homebrew

$ brew install docker
$ docker --version
Docker version 18.09.5, build e8ff056

Note that brew install docker and brew cask install docker is different. Some of the instructions about docker installation on Mac OS use the latter code that installs Docker as an Application, which you can see a good explanation.

⚠️ You can’t run Docker just after installing Docker. If you try, you’ll see:

$ docker run hello-world
docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?.
See 'docker run --help'.

This is because on macOS the docker binary is only a client and you cannot use it to run the docker daemon, because Docker daemon uses Linux-specific kernel features, therefore you can’t run Docker natively in OS X. So you have to install docker-machine in order to create VM and attach to it. (source)

Docker-Machine installation via Homebrew

$ brew install docker-machine

⚠️ ️️ You can’t still create a machine because you don’t have VirtualBox. If you try, you’ll see:

$ docker-machine create --driver virtualbox default
Creating CA: /Users/yutafujii/.docker/machine/certs/ca.pem
Creating client certificate: /Users/yutafujii/.docker/machine/certs/cert.pem
Running pre-create checks...
Error with pre-create check: "VBoxManage not found. Make sure VirtualBox is installed and VBoxManage is in the path"

So, download VirtualBox. You can only cask install (you can confirm this by running brew search virtualbox).

VirtualBox installation via Homebrew

$ brew install virtualbox --cask

⚠️It’s possible you’ll fail to install VirtualBox with an error message like this:

When you do fail, turn on System Preference and see if ‘System software from developer “Oracle America, inc” was blocked from loading.’ If you see that message, click Allow button and try to install again. (Sadly when you still fail to install, Daniel Meechan will help you more.)

Click “Allow” button and it’s done!

Successfully installed? Great!

Create a new virtual machine

Then, let’s create a machine. You can create a machine by docker-machine create (name)with--driver flag to specify a provide on which the machine is created on. (docker doc)

$ docker-machine create --driver virtualbox default
[...]
Docker is up and running!
To see how to connect your Docker Client to the Docker Engine running on this virtual machine, run: docker-machine env default

Run docker-machine ls and you’ll see your ‘default’ machine is now created.

$ docker-machine ls
NAME      ACTIVE   DRIVER       STATE     URL                         SWARM   DOCKER     ERRORS
default   *        virtualbox   Running   tcp://192.168.xxx.xxx:xxxx           v18.09.5

Few more steps. As noted in the output of the docker-machine create command, run the following command to tell the Docker ‘which machine’ to execute docker command to.

$ docker-machine env default

And connect your shell to the new machine. Here I’m using zsh (Docker supports bash cmd powershell emacs , fish and SHELL can be OK).

$ eval $(docker-machine env default)

Finally, let’s check that all installation process is achieved correctly!

$ docker run hello-world

When you finish playing around with Docker this time, don’t forget to stop the machine with this command. ( You can check the status docker-machine ls)

$ docker-machine stop default

What we have done?

All the way long, we did it. What we did are the following things:

• installed Docker, Docker Machine, VirtualBox
• docker-machine createcreated a new Docker virtual machine (named ‘default’)
• docker-machine envswitched your environment to your new VM (named ‘default’)
• evaluse the docker client(your local computer/terminal) to create, load, and manage containers
• docker runDocker client (your terminal) created the Docker deamon
• pulled the first image ‘hello-world’
• The Docker deamon created a container, streamed out that output to the Docker client
• docker-machine stopshut down the virtual machine

Docker Machine CLI commands

active
config
create
env
help
inspect
ip
kill
ls
mount
provision
regenerate-certs
restart
rm
scp
ssh
start
status
stop
upgrade
url

Thank you all for reading! Hope this helps you a little.

Bye

Yuta.

Resources

Get started with Docker Machine and a local VM

Building A Web Or Mobile App?

Crowdbotics is the fastest way to build, launch and scale an application.

Developer? Try out the Crowdbotics App Builder to quickly scaffold and deploy apps with a variety of popular frameworks.

Busy or non-technical? Join hundreds of happy teams building software with Crowdbotics PMs and expert developers. Scope timeline and cost with Crowdbotics Managed App Development for free.