The canonical recipe to install Docker Toolbox on Mac OS X
A year ago I moved from working on a Linux based development setup to a MacBook Pro and thus Mac OS X. Over the course of the last months I moved most of my development to Docker based workflows.
Since available documentation on running current Docker on OS X this should come in handy for some people out there.
Let’s begin with preparing the system for our needs, and get Homebrew and Caskroom installed.
Start by creating a GitHub token:
If you prefer to do this the old fashioned way, browse to your account settings on GitHub and manually create a token.
To avoid hitting the GitHub API limits when installing via Homebrew we now export our token:
Finally we can prepare our system for installing Docker:
Let’s step through this.
First we install the Xcode command lines tools required by Homebrew to build some packages from source. Next we pull the Homebrew installer, and finally we enable the Caskroom tap and grab VirtualBox along with the extension pack.
If you open your Dashboard or Spotlight and type
virt you should see the
VirtualBox icon. Awesome!
But why VirtualBox? Docker depends on the Linux kernel to run. As we are running Mac OS X (which basically is a BSD based system), Docker will use VirtualBox to run a minimal Linux machine with Docker installed.
Installing Docker these days is done by pulling in the Docker Toolbox. This includes the Docker Client, Docker Machine and Docker Compose. For those preferring a visual environment, Kitematic (a simple Docker GUI) is included, too.
You can verify your installation by running
docker version which should as
of now show similar output to this:
Set sail towards new adventures
If you’re like me, you want things to run out of the box. By default Docker Toolbox comes with an additional terminal shortcut that prepares a Docker Machine based environment for you. Me, I like to use the default terminal.
So we create a Docker Machine ourselves:
This fires up a minimal Docker environment in VirtualBox named default (you can also see this in the VirtualBox UI).
Now wouldn’t it be nice if this was running even after we log out or reboot? Happens rarely, but it does.
Thus we will add a LaunchAgent configuration for starting up our default Docker machine by creating this configuration file:
Then we ensure proper permissions and enable the LaunchAgent configuration:
Hold it right there, this does not work!
I’ve tried running
docker psand it printed an error! You suck!
Yes, there is more. Since we run Docker Machine, we have to connect our Docker Client with the Docker service running inside the virtual machine.
Since Docker Machine is a nice one (just like Docker in general is), it will help us, so try out this:
These environment variables will help you connect your Docker Machine to the Docker service inside of VirtualBox.
Executing the recommended command does the trick.
Finally, Docker is working. Executing
docker ps should now print an (obviously)
empty list of running containers.
To avoid having to reconnect Docker Machine and the Docker service each time the terminal is closed, you can simply extend your Bash Profile by adding:
This concludes our Docker setup for Mac OS X.
From here on you could
- create an account on Docker Hub, and log in your Docker client
docker loginto publish your own containers.
- use the DroneCI CLI to build your projects inside Docker containers,
… and more. I recommend to review a few existing containers on Docker Hub build containers for your projects.
All code snippets in this post are made available to use under the MIT Licence.