Chris LaRose

Run Docker in VirtualBox with Vagrant on Mac OS X

Update (Oct 16, 2014): Docker 1.3 and the corresponding update to boot2docker obsoletes this workaround by allowing you to mount directories directy from OS X to Docker containers.

Docker used to include a nice Vagrantfile, and this was the preferred way to run Docker on OS X. Since version 0.8.1 (PR #4281), though, the Docker documentation refers Mac OS X users to boot2docker. boot2docker runs the Docker daemon in a VirtualBox VM, but the Docker client runs from the host Mac OS X machine. That’s super cool, and props to the Docker developers for getting that to all work. That said, I can’t stand it for doing any sort of application development because when you run docker run -v, host directories refer to the machine running the Docker daemon, not the client. This means that I can’t easily mount directories right from my Mac.

I advocate instead running both the Docker client and server in a virtual machine in VirtualBox using Vagrant. If you haven’t done so already, download and install both VirtualBox and Vagrant. Vagrant uses a text file named Vagrantfile to configure new virtual machines. By default, Vagrant will synchronize the contents of the directory in which a Vagrantfile resides to the VM’s /vagrant directory. This is very helpful if you’d like to modify source files on your Mac with your favorite tools and run corresponding Docker containers on the VM. Here’s a Vagrantfile to get you started:

# -*- mode: ruby -*-
# vi: set ft=ruby :


Vagrant.configure(VAGRANTFILE_API_VERSION) do |config| = "precise64"
  config.vm.box_url = ""
  config.vm.provision "docker"
  for i in 49000..49900 "forwarded_port", guest: i, host: i

This specifies a new 64-bit Ubuntu 12.04 virtual machine with Docker and conveniently forwards all ports in the range 49000..49900 from the host to the virtual machine. That way, if you run a web server (for example) from your VM, you can open a web browser from your Mac and see your site.

Then, we just start up the VM, establish an SSH connection with it, and start using Docker.

Your-Mac:docker-vm$ vagrant up
Your-Mac:docker-vm$ vagrant ssh
vagrant@precise64:~$ docker ps

Vagrant’s Docker Provisioner, by the way, can do some pretty neat tricks like building Docker images upon provisioning. Check out the docs.

blog comments powered by Disqus