boot2docker together with VirtualBox Guest Additions

How to mount /Users into boot2docker

Using boot2docker with my Mac, I want to seamlessly run something like:

docker run -i -t -v /Users/mattes/project1:/data/project1 ubuntu /bin/bash

UPDATE 17 Oct 2014:

As of Docker version 1.3 the work-around described in this blog post becomes obsolete.

Please read more here:

tl;dr Build your own custom boot2docker.iso with VirtualBox Guest Additions (see link) or download and save it to ~/.boot2docker/boot2docker.iso.

The issue is that boot2docker doesn’t support
-v /Users/mattes/project1:/data/project1 out of the box since it doesn’t include VirtualBox Guest Additions. It’s still unclear to me, if the VirtualBox Guest Additions will make it into boot2docker any time soon/ ever.

“we’re making boot2docker as simple and small as possible — so at this point, adding tools that are not relevant to all usecases (bare HW, vbox, vagrant, hyper-v, vmware, kvm, etc) is not on the plan. This may change in future, but we havn’t completed our original feature set yet.”

SvenDowideit (boot2docker repo owner) commented on May 30 (link)

Though, there is a pull request to include VB guest additions, see

So I tried to built my own custom boot2docker.iso following the steps from the pull request above. I ran into a lot of issues and problems, so I thought it would be nice to document the steps that worked out for me.

Prerequisites: The following assumes you already have boot2docker installed. If not, follow and use the Docker OSX Installer. Or use brew:

brew install docker
brew install boot2docker

Okay, so I basically build a new boot2docker.iso with this Dockerfile. It is completely based on the PR from steeve and all credits should go to him. In order to make the mount of /Users permanent for every boot2docker up I had to add some additional lines. See here. Personally, I think this hack is ugly. But I couldn’t find another way of doing it at the moment. (There is /var/lib/boot2docker/ for example, which might be a better place.)

Trying to set “Auto-mount” to “yes” DOESN’T WORK for me, unfortunately. I had to add the following.

Building that Dockerfile should save the boot2docker.iso in the resulting Docker image. To copy that iso file to the host system I often see:

# this does not work for me
$ docker run -i -t --rm mattes/boot2docker-vbga > boot2docker.iso

… which returns either an empty file or an iso file which doesn’t boot correctly. I tried that with different Docker versions and with Docker 1.0 obviously. The only thing that worked for me was:

# this works...
$ docker run -i -t --rm mattes/boot2docker-vbga /bin/bash
# and then in another shell:
$ docker cp <Container-ID>:boot2docker.iso boot2docker.iso

So once you have your fresh boot2docker.iso on your host system replace the old one at ~/.boot2docker/boot2docker.iso:

$ boot2docker stop
$ mv ~/.boot2docker/boot2docker.iso ~/.boot2docker/boot2docker.iso.backup
$ mv boot2docker.iso ~/.boot2docker/boot2docker.iso

Now let VirtualBox know, which path you want to mount:

$ VBoxManage sharedfolder add boot2docker-vm -name home -hostpath /Users

And this should be it. Let’s verify.

$ boot2docker up
$ boot2docker ssh "ls /Users"

Now you can …

docker run -i -t -v /Users/mattes/project1:/data/project1 ubuntu /bin/bash

For the lazy: You could just download and move it to ~/.boot2docker/boot2docker.iso. Make sure to stop boot2docker before. Find the build log here.

EDIT 20 Jun 2014: updated boot2docker to version 1.0.1
EDIT 7 Jul 2014: updated boot2docker to version 1.1.0
Edit 11 Jul 2014: updated boot2docker to version 1.1.1
Edit 24 Jul 2014: updated boot2docker to version 1.1.2
Edit 14 Aug 2014: updated brew install commands
Edit 24 Aug 2014: updated boot2docker to version 1.2.0 and vbox to 4.3.14




Boot2Docker is a lightweight Linux distribution made specifically to run Docker containers. It runs completely from RAM, is a small ~24MB download and boots in ~5s (YMMV).

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Matt Kadenbach

Matt Kadenbach

More from Medium

DecentWorld Metaverse On Bridging Our and Virtual Realities

Project: Ultiverse

Cyberpop Metaverse club- Vision &Mission

Come up, traveler, and listen… Omniverse DAO

Omniverse Dao & LayerZero Labs