Docker Toolbox is a cool tool for working with Docker containers on OS X and Windows, and it bundles Oracle’s VirtualBox.1 But if you have Hyper-V installed and active, you can’t also use VirtualBox.

Read on for how to use Hyper-V with Docker Toolbox …

Prerequisites

This guide assumes you have Hyper-V running on your machine, configured with an External Virtual Switch. It also assumes your system is Windows 10, but I would not be surprised to find that Windows 8.1 and Server 2012 R2 are also sufficient.

  • Windows 10 Professional or Enterprise
  • Hardware virtualization enabled (you do this in the BIOS of the machine)
  • Hyper-V installed
  • An external virtual switch configured in Hyper-V (use the Virtual Switch Manager in the Hyper-V Manager)

We would prefer to use an internal virtual switch, but that doesn’t work due to some bugs in IPv6 support in Docker Machine (as of version 0.5.6, build 61388e9). The bugs will likely be fixed in version 0.6, so when that comes out these instructions will be updated.

Installing Docker Toolbox

Download the Windows version of Docker Toolbox from here: https://www.docker.com/docker-toolbox. Run the install, accepting all the defaults.

VirtualBox cleanup

That installed Oracle’s VirtualBox, which is incompatible with Hyper-V—they cannot both be enabled on the system at the same time. The VirtualBox install adds some drivers and network adapters. Which means there is a little bit of cruft that you should clean up. To do that:

  1. In Control Panel, go to “Network and Internet”, then “Network and Sharing Center”, and select “Change adapter settings”.
  2. Disable the “VirtualBox Host-Only Network” adapter.
  3. In the properties of your ‘Internet’ adapter—the one probably called just “Ethernet” and through which you are connect to the LAN—uncheck “VirtualBox NDIS6 Bridged Networking Driver” and make sure “Hyper-V Extensible Virtual Switch” is checked.
  4. In the properties of each “vEthernet” adapter (which are Hyper-V virtual switches), uncheck “VirtualBox NDIS6 Bridged Networking Driver”

Create a Hyper-V VM using the Docker Machine

Now you’ll use Docker Machine to create a lightweight Linux VM, hosted by Hyper-V, and running the Docker Manager. Make sure you do have an external virtual switch configured in Hyper-V and that you know what it’s name is—you’ll need to supply that name on the command line.

  1. Open a command window using “Run as administrator”.
  2. cd to C:\Program Files\Docker Toolbox.
  3. Enter the command to create and provision the Docker VM …
docker-machine.exe create --driver hyperv --hyperv-virtual-switch "External Virtual Switch" --hyperv-cpu-count "1" --hyperv-memory "1024" --hyperv-disk-size "20000" mydockervm

In the command above you should supply the name of your virtual switch for the --hyperv-virtual-switch argument. The other --hyperv-* arguments are the default values, so you don’t need to supply them unless you want something different—for example, I usually set the CPU count to 2, not 1. Memory is specified in KB, and disk size in MB. Use some unique machine name, not “mydockervm”—remember this is using the external virtual switch, thus it will be visible on the LAN and will use the DHCP service of the LAN, and so you should avoid duplicating the name of another system on the network.

That command will create the VM and provision it via SSH. When it completes then you’ll see:

Docker is up and running!
To see how to connect Docker to this machine, run: docker-machine.exe env mydockervm

Connecting to your docker VM

In an administrative command window, enter this command to set some required environment variables:

docker-machine env mydockervm

Then you can SSH to the system using:

docker-machine ssh mydockervm

Note about SSH

If you have a command line SSH client already installed on the system, and it is in the path, then docker-machine ssh will use that. If no SSH executable is found, then docker-machine will use a built-in Golang version of SSH.

I’ve found that with docker-machine version 0.5.6 there are terminal issues with the Golang SSH from Windows. For instance, using vi in an SSH session doesn’t work well because the ESC key doesn’t seem to be communicate properly (so once you are in ‘insert mode’ in vi you can’t ESC back out to ‘command mode’ and thus cannot quit the vi session or save your edits).

My solution to this was to install PuTTY and open a separate SSH connection and terminal window with that tool. If you establish an SSH session with your Docker VM without using docker-machine ssh then you will be prompted for userid and password. Per the boot2docker image README, use docker for the userid and tcuser for the password.

Other useful commands

  • To stop the docker VM: docker-machine stop mydockervm
  • To start the docker VM: docker-machine start mydockervm
  • To restart the docker VM: docker-machine restart mydockervm
  • To delete the docker VM: docker-machine rm mydockervm
  • Other things: docker-machine --help

Now what?

OK, you’ve got your container host and can start learning about and using Docker containers. Here are some starting points and references:

To learn about Docker and containers, I’d recommend getting The Docker Book and working through it. Then use the Docker documentation and the Docker Cookbook to help you with specific applications of containers and Docker.

Have fun!

  1. so that you can run Linux VMs—Linux being necessary to host containers and the Docker Engine. ↩