Ayan Ray

Thoughts on Software Engineering

Easy and Reliable Docker Installation and Setup on Mac OSX

This post stems from my frustration with working with boot2docker and getting Docker setup with my Mac. I had to refer to several posts, several places, tried Kitematic, tried boot2docker, and always had issues with not many references available. Thankfully I’m familiar with working in this space so I’ll add my thoughts on getting docker setup on your Mac easily and reliably.

What is Docker?


Docker is a containerization wrapper that makes it easy to design, distribute, and maintain linux containers. Linux containers are a fairly recent technology that enables more fine grain control of compartmentalization. The common compartmentalization prior to containerization was virtualization, which has brought us a flurry of flexibility in hardware technologies allowing us to create and destroy virtual machines on top of physical machines. Unfortunately, this level of compartmentalization requires a large overhead because it’s basically creating an operating system inside of another operating system. This is useful in some cases like adding operating systems of a different types on top of other operating systems of different types (I.e. Windows inside of a Mac, for example). However, again, it has its trade offs as long boot times and a large disk footprints makes this too heavy if you just want to run a few processes. Containerization brings the next level of compartmentalization allowing an operating system to protect a process from other processes and placing them into their own sandboxes (one of the key reasons you do compartmentalization). There’s plenty of material on this so I urge you to read up, of which the Docker website is helpful but the more general concept of Linux containers being the technological breakthrough.

Setting Up Docker on Mac OSX

There are a few guides on how to setup Docker on Mac OS X and they are extensive and cover many use cases. For me, I just wanted to set it up as quickly as possible, and even that was a headache asI had to look at 3-5 blog posts to solve the various problems I had (ugh Guest Additions).
Here’s what worked for me:

What is Vagrant?

I am going to use Vagrant to simplify this process greatly. Vagrant is a Virtualization controller that basically is an API on top of a virtualization technology like VMWare or VirtualBox. I’ve used it before and always had a smooth experience.

Install the Latest Vagrant

Get it here: http://www.vagrantup.com/downloads.html

Install VirtualBox

You need this to control operating systems inside of Mac OSX. You can get it here: https://www.virtualbox.org/

Setup your Vagrantfile

The Vagrantfile is the configuration file for Vagrant. It is basically a ruby script. Place this file in any directory you wish, and note that this directory will become available inside your virtual machine (that runs docker).

Create a new file, name it Vagrantfile, and put this there:

Vagrant.configure(2) do |config|
config.vm.box = “ubuntu/trusty64”
config.vm.network “private_network”, ip: “″

Note, I am using ubuntu’s latest LTS. You can use whichever you want, and there are many available here: http://www.vagrantbox.es/

Run Vagrant

Now, in that folder, run

vagrant up

You’ll see a lot of activity, and if you are doing this for the first time, it will find and download that ubuntu LTS release from the vagrant repository. This might take a few minutes as the image could be large (2GB+). You also might want to play with the private IP address in case that address is taken. The vagrant up command will fail if you have a collision with the static IP. I prefer to use a static IP so it’s consistent when you boot the machine so pick one that doesn’t collide.

Enter the Virtual Machine (VM)

Now, in the folder where you ran vagrant up, you can now run:

vagrant ssh

You are now inside the VM, and you’ll see your user (whoami) as vagrant. If you “cd /vagrant”, you’ll see your Vagrantfile and anything else that was in the folder. This folder is mounted inside your VM effortlessly and you can now run docker processes that mount folders that are within this folder.

If you want to add more folders, you can do so easily in the Vagrant file:

Vagrant.configure(2) do |config|

config.vm.synced_folder “/Users/myusername/MyMacOSXFolder”, “/path_inside_vm”, type: “nfs”


More notes are available here:

Install Docker

Lastly, let’s install docker.

sudo apt-get update
sudo apt-get -y install docker.io
docker -h

There are plenty of guides from this point and some links at the bottom (the docker guide) are helpful to get familiar with it as a tool.

Why is this better?

Because getting Linux Guest Additions (the thing that mounts Mac OS X folders to Linux Folders) is tricky to get right. I didn’t have success with the boot2docker installation from Docker’s website and their version of Linux. I wasted a lot of time and didn’t want to any more time and as I know how to use Vagrant and Ubuntu and know how easy it is, I just went with it and it worked flawlessly without any deviation from the standard setup. There is more overhead with booting a larger Linux installation, but I’d rather have consistency than lose time having to debug something that should just work.

Helpful Links

  1. Working with Containers
    1. https://docs.docker.com/userguide/usingdocker/
    2. The official post on Docker on working with containers
  2. How to use Docker on OSX – The Missing Guide
    1. http://viget.com/extend/how-to-use-docker-on-os-x-the-missing-guide
    2. Long but pretty good. Would have liked it split into several posts and the mounting didn’t work for me at all.

Final Thoughts

I tried using that new slick UI Kitematic created but again had problems. The problem with UI’s vs command line is if you run into problems, things are obfuscated to avoid you having to debug it. This isn’t necessarily a bad thing as things should just work. But when you’re on the cusp of technology, you need more control and not waste any time. Again, my problems were almost always because of Linux guest additions and mounting folders from my Mac (to run files, etc.) so it very well could work perfectly fine for you. It didn’t for me and I’m 99% sure this method will always work as I’ve never had problems with it in the 2+ years I’ve been using Vagrant and Ubuntu.


« »

© 2017 Ayan Ray. Theme by Anders Norén.