Phusion white papers Phusion overview

Phusion Blog

Docker-friendly Vagrant boxes

By Hongli Lai on November 8th, 2013


We heavily utilize Vagrant in our development workflow. Vagrant is a tool for easily setting up virtual machines as development environments, making it easy to distribute development environments and making them reconstructible and resetable. It has proven to be an indispensable tool when working in development teams with more than 1 person, especially when not everybody uses the same operating system.

Lately we’ve been working with Docker, which is a cool new OS-level virtualization technology. Docker officially describes it as “iPhone apps for your server”, but being the hardcore system-level guys that we are, we dislike this description. Instead we’d like to describe Docker as “FreeBSD jails for Linux + an ecosystem to make it a joy to use”. Docker, while still young and not production-ready, is very promising and can make virtualization cheap and efficient.

Googling for Vagrant and Docker will yield plenty of information and tutorials.

Today, we are releasing Docker-friendly Vagrant boxes based on Ubuntu 12.04. Docker requires at least kernel 3.8, but all the Ubuntu 12.04 Vagrant boxes that we’ve encountered so far come with kernel 3.2 or 3.5, so that installing Docker on them requires a reboot. This makes provisioning a VM to be significantly more painful than it should be.

Update April 23 2014: we now also provide Vagrant boxes based on Ubuntu 14.04. The 12.04 boxes are still available. See the website for more information.

These boxes differ from the ones provided by in the following ways as well:

  • We provide 2 virtual CPUs by default, so that the boxes can make better use of multicore hosts.
  • We provide more RAM by default: 1 GB.
  • We provide a bigger virtual hard disk: around 40 GB. So that you don’t have to worry about running out of disk space inside your VM.
  • We use LVM so that partitioning is easier.
  • The memory cgroup and swap accounting are turned on, for some Docker features.
  • Chef is installed via the Ubuntu packages that they provide, instead of via RubyGems. This way the box doesn’t have to come with Ruby by default, making the environment cleaner.
  • Our VMWare Fusion boxes recompile VMWare Tools on every kernel upgrade, so that Shared Folders keep working even if you change the kernel.

These base boxes are automatically built from Veewee definitions. These definitions makes building boxes quick and unambigious. The entire building process is described in the definitions; no manual intervention is required.

We provide prebuilt boxes at, but you can build them yourself if you so wish.

The boxes are also available on Vagrant Cloud.

Related resources: Github | Prebuilt boxes | Vagrant Cloud | Discussion forum | Twitter

Using these boxes in Vagrant

If you have Vagrant 1.5, you can use our boxes through Vagrant Cloud:

vagrant init phusion/ubuntu-14.04-amd64
# -OR-
vagrant init phusion/ubuntu-12.04-amd64

On older Vagrant versions, you can modify your Vagrantfile to use our boxes. Here is an example Vagrantfile which works with both VirtualBox and VMWare Fusion. It also automatically installs the latest version of Docker.

# Vagrantfile API/syntax version. Don't touch unless you know what you're doing!

Vagrant.configure(VAGRANTFILE_API_VERSION) do |config| = "phusion-open-ubuntu-14.04-amd64"
  config.vm.box_url = ""
  # Or, for Ubuntu 12.04: = "phusion-open-ubuntu-12.04-amd64"
  #config.vm.box_url = ""

  config.vm.provider :vmware_fusion do |f, override|
    override.vm.box_url = ""
    #override.vm.box_url = ""

  if Dir.glob("#{File.dirname(__FILE__)}/.vagrant/machines/default/*/id").empty?
    # Install Docker
    pkg_cmd = "wget -q -O - | apt-key add -;" \
      "echo deb docker main > /etc/apt/sources.list.d/docker.list;" \
      "apt-get update -qq; apt-get install -q -y --force-yes lxc-docker; "
    # Add vagrant user to the docker group
    pkg_cmd << "usermod -a -G docker vagrant; "
    config.vm.provision :shell, :inline => pkg_cmd

You can login with username vagrant and password vagrant. This user has sudo privileges. The root user also has password vagrant.

The prebuilt boxes are available at

Final words

Enjoy these Vagrant boxes!

You may also want to check our other products, such as Phusion Passenger, which is an application server which makes Ruby, Python, Node.js and Meteor deployment extremely simple. Or simply follow us on Twitter.

  • Paul Bowsher

    ‘Docker officially describes it as “iPhone apps for your server”’

    Never seen that anywhere, and Google only turns up this blog post. Source please, as that’s a really stupid claim to make if they didn’t say it. It makes Docker look bad.

    I quote:

    think “iPhone apps for the server”

    Before their recent website revamp, they even had it on the about page.

  • Paul Bowsher

    I stand corrected.

  • ubermuda

    Is swap accounting enabled on these boxes?

  • These are standard Ubuntu 12.03 boxes with almost nothing installed, though with kernel 3.8. I don’t think swap accounting is enabled by default.

    Note that these boxes don’t include Docker. You’ll have to install the Ubuntu packages using APT and your favorite provisioner. The point of these boxes is to avoid having to reboot the VM as part of the Vagrant provisioning process, which is quite an awkward process.

    Although if people *want* it, we can add the Docker repo by default. Just let us know.

  • ubermuda

    That is precisely why I ask 🙂 I ran into the issue today on my own vagrant box, trying to limit memory for a container and running into the following message:

    WARNING: Your kernel does not support memory swap capabilities. Limitation discarded.

    Swap accounting must be enabled at kernel boot time through a parameter (passed by grub in our case).

    Long story short, anyone wanting to limit memory for a container using your boxes will actually have to reboot the VM as part of the provisioning process.

    This might not be mister Everyone’s use-case, but heh, it doesn’t cost much to be prepared and make those boxes docker-friendlier than they already are 😉

    More infos:

  • Interesting, I didn’t know about this boot-time option. I’ll look into enabling this by default.

  • We’ve now rebuilt and uploaded the VirtualBox box with swap accounting enabled. VMWare Fusion box is being uploaded.

  • ubermuda

    Awesome! You rock.

  • These are super useful, thanks for posting them!

    Sadly, I’ve found a problem in the VMware base box: If you bring it up initially, everything works, but the second time you bring it up (after a `vagrant halt ; vagrant up`), it hangs trying for the HGFS kernel module to load.

    I could reproduce this in a packer box that I’m building myself, and I think I have tracked the root cause of this down to the kernel upgrade going through and the vmware tools being installed only for the old kernel. The solution for me was to install the kernel 3.8.x, reboot, and only after the reboot to install vmware tools.

  • We actually already take care of this. We patched the VMWare Tools and integrated them into DKMS, so that on every kernel upgrade the tools are automatically recompiled.

    But maybe you provisioning script upgraded the kernel to a version that the VMWare Tools couldn’t automatically recompile against. Try modifying your provisioning scripts so that they don’t upgrade the kernel.

  • Hum, not really. All this vagrantfile does is to use the “docker” provisioner to bring a container up. Maybe vagrant’s automatic installation of docker on Ubuntu installs a new kernel also?

  • Could you check whether your kernel is being upgraded? It has worked for us so far.

  • Florian Heigl

    Thanks for your description of Docker. After all just a LXC wrapper + tarballs like Vagrant is a VirtualBox wrapper plus images?

    I’ll just need to figure out the hype. Is it just so amazing if you don’t have the same background (chroots, jails, zones, xen PV, NFS netbooting default) and it comes nicely packaged? Or what the f*** am I missing why this is so amazing?

  • Barry A.

    Note on memory and cgroup accounting: the Docker KB details were deleted but a PR was opened to restore them.

  • Barry A.

    Correct, it’s not enabled by default. There will be a couple of “WARNING:” running `docker info` if it’s not enabled. Fix:

  • Justizin

    it kind of makes sense, because iOS / OSX apps are sandboxed, but Docker is nowhere near as fun as Bundles.

  • TK

    By the way, the boxes no longer work:

    Failed to mount folders in Linux guest. This is usually because the “vboxsf” file system is not available. Please verify that the guest additions are properly installed in the guest and can work properly. The command attempted was:

    mount -t vboxsf -o uid=`id -u vagrant`,gid=`getent group vagrant | cut -d: -f3` /vagrant /vagrant
    mount -t vboxsf -o uid=`id -u vagrant`,gid=`id -g vagrant` /vagrant /vagrant

    Remove your local copy of the box in ~/.vagrant.d/boxes and try from scratch. Not working here.

  • There’s currently an issue with version 2014-04-21 of the Ubuntu 12.04 VirtualBox box, which we’re still investigating:
    In the mean time, you can use an older version of the box, version 2014-02-01:

    Watch the discussion forum for updates:!forum/passenger-docker

  • hi,

    Ive just updated *Vagrantfile” presented in this post.
    Here is it: