How to setup Docker on OS X.

If you are a geek like me, I’m sure you heard about Docker. In short it’s about running a very small virtual machine just for one service. A lot of people tried to explain it better before me. So ask Google if you want to learn more.

Recently I spent some hours playing with docker. In a short series of posts I want to share my learnings. This first post is about setting up Docker on your Mac. Docker does not run natively on OS X. Because this whole LXC virtualization stuff is not compatible with it. But some smart people found a way around that: Just run a Linux in a virtual machine and put Docker in there. You don’t even have to do it yourself. There is a project named Boot2Docker. The package contains VirtualBox plus a very small Linux VM (CoreOS) which runs Docker for you. Once that is up you can play with Docker from you OS X console.

Step 1: Download and install boot2docker

You can download the package from here. Then install it like any other OS X application.

Step 2: Setup Docker

Once you’ve installed boot2docker open your terminal app and initialize the virtual machine with this command:

boot2docker init

The newest version of the VM will be downloaded. When this is done, you can start the virtual machine by running:

boot2docker up

The Docker command line app looks for an environment variable DOCKER_HOST to connect to docker. You can set this up with the following command:

export DOCKER_HOST=tcp://localhost:2375

This works because the boot2docker VM has set up port forwarding. Calls to Docker’s port (2375) on localhost will be forwarded to the VM.

Now, when you run docker ps you should see something like this:


Congratulations, you can now start dockering!

Step 3: Hosts

After setting up boot2docker I usually do some stuff for convenience. This includes setting up a hostname for the Docker container on my OS X box and downloading a default ubuntu image.

Open the file /etc/hosts as root with your favourite editor: sudo vim /etc/hosts and add the following line at the bottom:    docker

I got the IP by running boot2docker ip. You should see the same here but things can change… Now try if it worked by running ping docker. The host should be reachable. If you like you can set the DOCKER_HOST variable using the new hostname.

Later you can reach all your services running in a Docker container by calling them via docker:<port>.

Step 4: Snapshot

The standard Ubuntu Trusty image is the one I usually use for new images.

docker pull ubuntu:trusty

After pulling the default image I save the virtual machine’s state into a snapshot. This way I can go back to a clean state when I messed something up or the vm got too large.

boot2docker stop
VBoxManage snapshot "boot2docker-vm" take "Clean state"

Restoring the snapshot works with this command.

VBoxManage snapshot "boot2docker-vm" restore "Clean state"

Step 5: Test you setup

You can now run your first “Hello World!” using Docker:

docker run ubuntu:trusty /bin/echo 'Hello world'