In-Depth

First Look: Docker Machine Preview

The new Docker Machine preview lets you build Docker VM hosts on various compatible OS hosts, hypervisors and clouds.

• By Brien Posey
• 05/07/2015

As Microsoft moves to embrace containers to provide virtual machine (VM) and application portability, the company is among numerous players that have aligned with Docker Inc. to enable cross-platform compatibility. Microsoft first announced support for Docker containers in the Microsoft Azure cloud service a year ago followed by last fall's agreement by the two companies to ensure Windows containers are compatible with Docker.

Experts say containers are poised to become a popular means of providing portability between server platforms, VMs and public clouds because the application doesn't need to undergo changes in order to run on a different platform. A virtualized application can, for instance, run on a laptop or in the cloud.

In spite of the compelling capabilities of Docker, many Windows Server shops might be reluctant to use Docker containers because they're designed to run in Linux environments. Docker recently created a utility called Docker Machine designed to deploy Docker containers in proprietary environments. For example, Docker Machine can be used to deploy Docker to Hyper-V, VMware hypervisors and even to Azure. With the release of the Docker Machine preview, it's now possible to run Docker containers in a Hyper-V environment.

Deploying OpenSSH
Before you can use Docker Machine, you'll have to deploy OpenSSH on your Hyper-V server. One of the OpenSSH components (SSL-KeyGen) is used in the creation of the Docker Machine. Although OpenSSH is an open source application originally designed to run on Linux, there's a Windows version available (download here). Upon downloading the .zip file and extracting the application bits, run the installer and follow the prompts. The actual installation process is simple, but there are a couple of tasks you'll need to complete before you'll be able to use OpenSSH.

As you work through the installation wizard, you'll see a pop-up message that states:

"Before starting the OpenSSH service you MUST edit the C:\Program Files (x86)\OpenSSH\etc\passwd file. If you don't do this, you will not be able to log in through the SSH server. Please read the readme.txt or the quickstart.txt file for information regarding proper setup of the password file."

Setting up the password file (and the as-yet-unmentioned group file) is really easy to do. In fact, you only have to run four commands. The instructions can be found at C:\Program Files (x86)\OpenSSH\Docs\quickstart.txt and list the exact commands you'll need to use.

You also must add OpenSSH to your server's path. This is necessary because it'll allow Docker to locate the SSL-KeyGen utility.

To add OpenSSH to the server's path, right-click on the Start button and select the System command from the shortcut menu. When the System dialog box appears, click on Advanced System Settings. This will cause the System Properties dialog box to be displayed. Now, click on the Environment Variables button. You'll find the path in the list of System Variables (you have to scroll down). Edit the path and append C:\Program Files (x86)\OpenSSH\bin to the existing path. Click OK three times to complete the process. The new path won't be used until you reboot the server.

Using Docker Machine
Now that OpenSSH is installed, it's time to download Docker Machine (download here). This article is based on version 1.0, the beta release issued in February.

Once the download completes, save the executable file to an easy-to-find folder (I put it in a folder named C:\Docker on my machine).

Now, open an elevated Command Prompt window and navigate to the folder where you saved the executable file. If you attempt to run the file, you'll see the file is meant to be used from the command line and there are a number of different switches available for you to use (see Figure 1).

Because the goal is to use Docker Machine to get the Docker environment up and running on Hyper-V, you have to use several different command-line switches. The first switch you'll need to use is Create. This tells Docker Machine you want to create a Docker host.

The next thing you'll have to provide is a driver. The driver is used to establish the platform where Docker will run. Docker normally runs inside VirtualBox. You can run Docker within Hyper-V or Azure because Docker Machine includes a Hyper-V driver and an Azure driver. You specify the driver by using the –D switch, followed by the driver name.

The last thing you have to specify is the name of the Docker Machine you want to create. For the purposes of this article, I'm going to call my Docker Machine LocalDev.

Next, you must verify no Docker Machines currently exist. To do so, enter the command:

Docker-machine_windows-amd64 ls

In this scenario no Docker Machines currently exist, which you can see in Figure 2.

Now, create a Docker Machine using the command syntax. Because you're creating the Docker Machine on Hyper-V, you'll use a driver named hyper-v. The actual command you must use is:

Docker-machine_windows-amd64 create –d hyper-v LocalDev

If you've done everything correctly, then Windows will begin creating the Docker Machine see (Figure 3.)

When Things Go Wrong
Hopefully you now have a Docker Machine up and running. However, Docker Machine is currently in beta and things can and sometimes do go wrong. What should you do if you get an error message during the Docker Machine creation process? First, check if the Docker Machine was partially created. To do so, enter the same command as earlier, when you verified no Docker Machines exist on your machine:

Docker-machine_windows-amd64 ls     

This command shows you the current state of any existing Docker Machines. Let's presume a Docker Machine is displayed within the results, but you received some errors during the creation process. Unfortunately, you can't just reattempt the creation because Docker Machine won't overwrite an existing machine.

In this type of situation, you should open the Hyper-V Manager. Depending on how far Docker Machine made it into the creation process, you may have a Hyper-V VM with the name you specified for the Docker Machine. This VM might even be running. The current Docker Machine build is a bit flakey and sometimes returns errors when no problem actually exists. During one of my tests, for example, I received an error message saying the Docker Machine had failed to start the VM. Even so, I was able to manually start the VM using Hyper-V Manager with no problems.

In other cases the errors returned by Docker are all too real and you'll have little choice but to recreate the Docker Machine. Before you can reattempt the Docker Machine creation process, you'll need to delete the existing VM, but don't do it through the Hyper-V Manager. You'll need to remove the VM using the command line instead.

Before you remove the Docker Machine, it's a good idea to look at the VM settings within the Hyper-V Manager and confirm the location of the virtual hard disk. In some cases it's necessary to manually remove VM components, so you need to know where the VM is being stored. The virtual hard disk will normally be stored within your user profile at C:\Users\<your user name>\.docker\machine\machines\<Docker machine name>\disk.vhd. You can see the location of my Docker Machine virtual hard disk in Figure 4.

To remove the Docker machine, go back to the Command Prompt window and enter the following command, Docker-­machine_­windows-­amd64 rm LocalDev, as shown in Figure 5.

In some cases the removal process won't work as it should. This is especially true for failures that occur early on, before the Hyper-V VM is created. In those types of situations you can append the –F switch to the end of the removal command to force removal of the Docker Machine.

As you can see in Figure 5, you can confirm the removal by using the Docker-machine_windows-amd64 ls command. Once you confirm the Docker machine is gone, you'll need to check to make sure the Hyper-V components (such as the virtual hard disk) have also been removed. You can do this by opening File Explorer and navigating to the path of the VM. If you find any remnants of the VM, go ahead and remove them.

Testing Your Docker Machine
Once you get your Docker Machine up and running, you'll need to make sure it's working properly. When you created the Docker machine, you might have noticed the installer downloaded an ISO file called Boot2Docker. If you look back at Figure 4, you'll notice the installer has linked this ISO file to the VM DVD drive. The VM boots from this ISO file. If you open the VM console, you should see the Boot2Docker environment (see Figure 6).

If you've ever taken a programming class in school, you'll probably remember the old "Hello World" program. Believe it or not, Docker has its own Hello World program you can use to verify Docker is working properly. To run the Hello World test, enter the follow­ing command in the Boot2Docker VM:

Docker run hello-world

Upon executing this command, you should see a Hello from Docker message (see Figure 7). More important, Docker confirms four things have happened:

1. The Docker client contacted the Docker daemon.
2. The Docker daemon pulled the Hello World image from the Docker Hub (unless it was locally available).
3. The Docker daemon created a new container from the Hello World image. This container is used to run the executable that produces the output shown in Figure 7.
4. The Docker daemon streamed the output to the Docker client, which caused the output to be displayed.

In other words, the Hello World program does more than just echo a block of text. It actually confirms the ability of the VM to create and use a Docker container.

Another way you can test your Docker Machine is to enter the Docker Info command. Doing so should return a number of different statistics about your Docker Machine.

Next Steps
As you can see, it's relatively easy to get Docker up and running in a Hyper-V environment. Yes, Docker Machine is still a little bit buggy, but those bugs should be fixed by the time Docker provides a full release of Docker Machine. For right now, though, you can use Docker in a lab to get used to working with the Docker environment.