Guide to Docker on OS X

Guide to Docker on OS X


To follow this tutorial, we need a working installation of OS X on our computer. Having Homebrew installed could also be helpful, although not mandatory.


A lot has happened in the Docker ecosystem recently – native Windows support, Docker 1.6, Docker machine, and Docker compose. But when it comes to OS X, we still need Boot2Docker and it can sometimes be difficult to have the same workflow afforded to us by the native version.

This tutorial is an updated guide about running Docker on OS X. Some elements come from previous guides, others are completely new, and the rest are just personal tips I use to improve my Docker workflow while working with Docker on my Macbook Air.

Installation and set up

Since OS X can’t natively run Docker like Linux, we will need to install an extra layer that will emulate a Docker host, and that’s what Boot2Docker is for.

This part has been explained in the article dedicated to running Boot2Docker on Windows, take a look if you want to know more about it.

First we’ll need to install VirtualBox. We just need to go to the VirtualBox website, grab the dmg, and install it.

In order to get Boot2Docker, we have two possibilities:

  1. Download the latest .pkg file from the Github page of the project.
  2. Install it with Homebrew using the command line:
$ brew update
$ brew install docker
$ brew install boot2docker

Now the next step is initiating the Boot2Docker VM. This will download the latest ISO file so we just have to run this once.

$ boot2docker init

In order to start the VM after the download is finished, we just need to run

$ boot2docker up

When the VM is running we should see some ENV variables displayed on the screen. We need to set these up to access the actual Docker host. We can either copy and paste the exports commands displayed or run the boot2docker shellinit command. But in order to save ourselves from inputting repetitive commands, we’ll make these variables permanent by writing them manually in a bashrc or zshrc file.

One of these variables is the DOCKER_HOST which contains the IP of your VM where the Docker host is located. By default, the IP address is but it’s possible that, due to network conflicts for instance, this IP might change. In case we forget the IP address we can simply run

$ boot2docker ip

which will print the current IP address of your Boot2Docker VM on your terminal.

At this point of the guide, we should have a running Docker environment on OSX, we can try some Docker commands to be sure that everything has been set up properly:

$ docker version
Client version: 1.6.0
Client API version: 1.18
Go version (client): go1.4.2
Git commit (client): 4749651
OS/Arch (client): darwin/amd64
Server version: 1.6.0
Server API version: 1.18
Go version (server): go1.4.2
Git commit (server): 4749651
OS/Arch (server): linux/amd64

Now let’s see how we can solve some tiny issues that Boot2Docker brings in order to improve our Docker workflow.

Shared directories

A lot of older tutorials described a heavy and complicated process to make the use of local mac folders with Docker containers possible. It involved adding VirtualBox Guest Additions and creating a custom Boot2Docker .iso file.

However, since Docker 1.3, it’s possible to use host-mounted volumes in a more “Docker natural” way by using volumes :

docker run -v /Users/username/myfolder:/folder yourimagename ...

As we can see, it’s easier today to share folders than it was several months ago. If you’re a fan of Docker compose you can immediately see the benefits of such improvements. The previous command simply mounts the directory /Users/username/myfolder directly from your Mac on the mounting point /folder of your container.

However, it’s important to note that, with the current settings of Boot2Docker, it’s apparently only possible to mount directories that are in /Users. Another issue, that can be really annoying for some developers, is the inability to write on those shared directories due to the use of vboxfs when boot2docker mounts volumes.

This issue has been debated for some time on a Github issue of the project, and it seems that @paolomainardi has a great solution.

Here’s the link in case you need it and want to try it for yourself:

Docker host IP and port forwarding

One of the classic problems of Boot2Docker is the port forwarding issues and the VM’s IP. This has the potential to disrupt our workflow because it feels like you’re running Docker on a distant server instead of having the native feel of Docker.

One of my favorite solutions is to edit the /etc/hosts/ file and add a custom domain name so I don’t mess up my computer or my Boot2Docker VM with port forwarding.

Just add the following line to your /etc/hosts/: boot2docker

With this, we avoid typing the Boot2Docker IP every time we want to access our running apps. It’s more convenient and really easy to set up!

However, on the Boot2Docker Github project documentation, you can find a way to forward all your Docker ports to your localhost. Use it with caution!

Some tips

Right now, we have an improved Docker developer environment on OS X. There are some additional tips that a lot of Docker user are sharing through different blog posts that can really make Boot2Docker, and even Docker itself more convenient to use. Here are some I personally use:

When we stop a container, it disappears from the list of running containers in docker ps, but if we type docker ps -a it will show both running and stopped containers. So far, Docker allows you to use the docker rm command with only one container id at a time. Here’s a command that can help with that issue and remove all the containers with an “Exit” status at once:

sudo docker ps -a | grep Exit | awk '{print $1}' | xargs sudo docker rm

Same goes with untagged images, you can remove all of them with this simple command:

sudo docker images | grep none | awk '{print $3}' | xargs sudo docker rmi

Last addition, which is a killer app for Docker on OS X: Boot2Docker status which is an OS X menu bar application for monitoring the state of your boot2docker virtual machine so you don’t waste sweet, sweet memory on a VM you aren’t using.

It also allows you to start/stop your Boot2Docker VM with a single click.

Tagged with: , ,
Posted in Tutorial
15 comments on “Guide to Docker on OS X
  1. Some suggestions:
    * docker-machine (also available with brew) is a good wrapper around boot2docker. It might help to orchestrate your OS X machine as well as other hosting providers.
    * “sudo docker images -q –filter ‘dangling=true’ | xargs sudo docker rmi” is a good alternative to remove untagged images.

  2. Craig Maynard says:

    Re: “Another issue … is the inability to write on shared directories.”

    I’m using boot2docker v1.6.2 to run ubuntu, and I am able to create and update files in the shared directory.

  3. davidrogers85 says:

    Kitematic is a pretty great tool for anyone on Mac (soon to be cross-platform, as it’s an Atom Electron project) too.

  4. Very nice article and thanks for quoting me, in the meanwhile i’ve made some little progress about NFS mounting, check it out:
    I’ll keel you updated 🙂

  5. Arve Nygård says:

    > awk {‘print $3}’
    Looks like you have a typo in the last command in your post (misplaced quote character). Might want to correct that.

  6. metazorg says:

    Thanks for the article. Have you checked out the docker-osx-dev image. The author has done some experiments with host to container file syncing times.

  7. Francis Kim says:

    This way of using Boot2Docker is deprecated, here’s the new instructions for OS X:

  8. farming simulator 15 free says:

    Overall Farming Simulator 2015 it is a very enjoyable
    expertise on the other hand could be improved in the textures.

  9. Baju muslim says:

    Postingan yang sangat bagus , saya percaya ini amat
    berguna untuk mereka yang membaca, saya nantikan pos selanjutnya ,
    terutama mereka yang sedang mencari Busana Muslimah dan mereka yang sedang
    belajar untuk menekuni dunia fashion

  10. […] can be installed on OS X in various ways, most notably Docker Toolbox or homebrew. I was previously using docker-machine with Parallels but recently I discovered Dlite which […]

  11. kitchen says:

    Saeco also created the unique Vienna and the Incanto classic.
    A decorator will help guide you through that process and
    show you how to use color to its fullest advantage. Two of the points are on the spout from where the water spews out,
    another is on the back of the neck, and the fourth one is close
    to the base of the faucet.

Leave a Comment

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: