Installing Docker: Fixes for common problems

Installing Docker: Fixes for common problems

As of May 23rd IBM Bluemix Container Service now provides a native Kubernetes operations experience while removing the burden of maintaining master nodes. Kubernetes itself is based on the Docker engine for managing software images and instantiating containers. Get the details.

Bluemix includes support for running Docker containers and “Bluemix Launches IBM Containers Beta Based on Docker” explains how to get started. However, if you’re developing on a Windows platform, you may encounter some problems getting the Docker runtime installed and running successfully. This post describes problems I discovered when installing Docker on Windows, how I found advice for fixing those problems, and what I did that successfully resolved them.

Overview of problems encountered and fixes

Docker containers run natively in Linux, but they can also run on Windows using Boot2Docker. Boot2Docker for Windows includes an installer to ensure that Boot2Docker is installed correctly, but as of v1.5.0, the installation claims to complete successfully but I found that Boot2Docker didn’t run correctly.

This post documents how to resolve two issues:

1. Boot2Docker Start shortcut doesn’t work – the Boot2Docker Start shortcut doesn’t run the start.shscript in a Bash shell, associate the .sh file extension with the <Git home>/bin/sh.exe program or some other Bash shell emulator for Windows.

2. Boot2Docker password – the Boot2Docker VM incorrectly requires a password; run these commands to update the VM:

   • run boot2docker delete to get rid of your VM

   • run boot2docker download to get the latest ISO

   • run boot2docker init to create a new VM

Now you should be able to successfully run the hello-world container, confirming that Docker is indeed installed and running successfully. Now you’re ready to run Docker containers on your Windows computer! For more details, continue reading the following sections.

Installing Docker for Windows

Docker runs natively in Linux, but since Windows isn’t Linux, you first need to install a Docker foundation on Windows called Boot2Docker. This foundation runs a Linux virtual machine (VM) on Windows, then the Docker containers run in that Linux VM.

The Docker utilities are— not too surprisingly —available at Docker’s website. Specifically, the downloads and instructions for installing on Windows are located at Docker for Windows. That links to the page for downloading the latest version of the Docker for Windows Installer, which as of this writing is v1.5.0 of the boot2docker/windows-installer project on GitHub. From that page, you can download docker-install.exe.

What should happen

Ideally, when you run you run the Docker for Windows Installer (docker-install.exe), Docker installs successfully and can run correctly. When Docker runs correctly, Boot2Docker runs a Linux virtual machine on Windows. To test the install, you can run a simple hello world program that Docker provides.

Once Docker is installed, to test the install, start Boot2Docker. At the Docker command prompt, run the command “docker run hello-world” like so:

Boot2Docker version 1.5.0, build master : a66bce5 - Tue Feb 10 23:31:27 UTC 2015<br>
Docker version 1.5.0, build a8a31ef<br>
docker@boot2docker:~$ <strong>docker run hello-world</strong>

That simple program responds with “Hello from Docker. This message shows that your installation appears to be working correctly.” The output looks like this:

Boot2Docker version 1.5.0, build master : a66bce5 - Tue Feb 10 23:31:27 UTC 2015<br>
Docker version 1.5.0, build a8a31ef<br>
docker@boot2docker:~$ <strong>docker run hello-world</strong><br>
Unable to find image 'hello-world:latest' locally<br>
511136ea3c5a: Pull complete<br>
31cbccb51277: Pull complete<br>
e45a5af57b00: Pull complete<br>
hello-world:latest: The image you are pulling has been verified. Important: image verification is a tech preview feature and should not be relied on to provide security.<br>
Status: Downloaded newer image for hello-world:latest<br>
<strong>Hello from Docker.<br>
This message shows that your installation appears to be working correctly.</strong><p></p>
<p>To generate this message, Docker took the following steps:<br>
1. The Docker client contacted the Docker daemon.<br>
2. The Docker daemon pulled the "hello-world" image from the Docker Hub. (Assuming it was not already locally available.)<br>
3. The Docker daemon created a new container from that image which runs the executable that produces the output you are currently reading.<br>
4. The Docker daemon streamed that output to the Docker client, which sent it to your terminal.<br>
</p>

That is the output you get if Docker has installed successfully and runs correctly. The rest of this post describes problems I experienced with my Docker install and how I resolved them.

Details of problems encountered and fixes

When I installed Docker on my Windows 7 laptop, it initially did not run successfully, so I had to take a couple of additional steps to get it working. Here’s a brief summary. The following sections have greater detail.

First issue: Boot2Docker Start doesn’t work

Problem: The Boot2Docker Start shortcut doesn’t run. Rather than running the start.sh script, the shortcut opens the script in an editor such as WordPad.

Solution: Edit the Windows file association for the .sh file extension to make the extension’s default program <Git home>/bin/sh.exe. Then the script will run in a Bash shell like it’s supposed to.

Second issue: Boot2Docker password

Problem: When the start.sh script tries to run the VM, a password is needed.

Solution: The ISO file is out of date. Get the latest ISO and create a VM from it with these commands:

• run boot2docker delete to get rid of your VM

• run boot2docker download to get the latest ISO

• run boot2docker init to create a new VM

The following sections explain the problems in detail and describe how I figured out what was causing them and how to fix them.

Problem #1: Boot2Docker Start shortcut doesn’t work

The Docker for Windows Installer creates two shortcuts (if you select this option), both are called Boot2Docker Start, located on the desktop and in the Start menu. When I ran this shortcut, it opened start.sh in WordPad.

Hmm, this doesn’t look like Docker starting. I suppose WordPad was so I could edit the script, but I didn’t want to edit it, I wanted to run it. The first line of the script says it’s a Bash shell script, so it expects to run in a Bash shell:

"#!/bin/bash"

That’s interesting, because Windows doesn’t run Bash shells. Windows scripts are batch files. So why is the Docker shortcut trying to run a Bash script on Windows and what do I do about it?

After some searching (using Google), I found this issue documented in the aforementioned boot2docker/windows-installer project on GitHub: Windows 8.1 prof (64 bit), not able to run Boot2Docker #31:

<em>On desktop, when click "Boot2Docker Start" link, it opens in my NotePad++. The file is:<br>
C:\Program Files\Boot2Docker for Windows\start.sh</em>

Yup, that’s the problem I was having! Suggested fixes are:

• Lots of uninstalling, rebooting, reinstalling, and more rebooting

• Add “C:\Program Files (x86)\Git\bin” in the Windows path

• Go to Default Programs->associate a file type or protocol — Change the settings for .sh to the bash.exe under Git/bin directory

• Write a batch script that sets the path and runs the Bash script

Here’s how I ended up resolving the problem. As you can see, finding the solution took a lot of trial and error, some of which may have contributed to the solution but a lot of which was probably unnecessary.

When I ran the Docker for Windows Installer and accepted the defaults, it decided not to install Git. This was shown on the installer’s Select Components page, though I didn’t think much of it at the time.

Docker for Windows requires three different components:

As shown in the screenshot above, the installer decided not to install MSYS-git on my system. This is probably because I already had Git installed on my system. Be aware that these similarly named programs are all different:

ProgramPurpose

Git for the Windows platformGit SCM: Create local Git repositories, run Git commands

GitHub WindowsCreate Git repositories on GitHub, sync it with a local repositories

MSYS-Git for WindowsGit SCM with more features

Docker wants to install MSYS-Git, which wants to install in the same default directory as Git SCM. Since I already had Git SCM installed on my system, the Docker installer decided not to install MSYS-Git.

Not knowing why Docker wasn’t running on my System (remember, it was opening the Bash sell script in WordPad), following the instructions in Git issue #31, I uninstalled Git SCM as well as Boot2Docker and VirtualBox, rebooted, performed a full install of Docker (all three components, including MSYS-Git), and rebooted again for good measure.

After all that, when I ran the Boot2Docker Start shortcut again, the script opened in WordPad. So my efforts so far had not fixed the problem.

At this point, I began to wonder why Docker even needs Git to be installed. Docker is for running containers; Git is for managing source code. What do they have to do with each other?

Git issue #31 suggested adding the Git bin directory (C:\Program Files (x86)\Git\bin) to the system’s path. I found this document on how to set the path in Windows: How to set the path and environment variables in Windows. So I tried that. The shortcut still opened WordPad. I don’t know why adding directories to the path would help anyway; the path is used when running commands in a shell but not for running shortcuts. It would be helpful if I want to start Docker from a command prompt but isn’t going to fix my shortcut.

Since the Boot2Docker Start shortcut was a file with the .sh file extension, I decided that extension wasn’t associated with the right executable. I found this document on how to change the association for a file extension: Change which programs Windows uses by default. One of the suggestions in Git issue #31 is to set/change the file association for the .sh file extension. Would something in Git run .sh files? Git’s bindirectory has a bunch of executables; would any of them run a Bash script? git.exe? bash.exe (as suggested in Issue #31)? In the end, there’s a sh.exe file, so I decided to try that one.

Success! Once I associated .sh files with <Git home>/bin/sh.exe, the Boot2Docker Start shortcut would run.

Moral of the story: When installing Docker, confirm that Git is installed and that the .sh file extension is associated with sh.exe (or bash.exe). This way, the Boot2Docker Start shortcut will run in a Bash shell. Or instead of Git, ensure that some other package capable of running Bash shell scripts (e.g. win-bash, Cygwin, etc.) is installed on your system and that the .sh file extension is associated with the appropriate program in the package.

Problem #2: Clearing the Boot2Docker password

Now I tried to run Boot2Docker for the first time. (Not just run the shortcut, but actually have the shortcut run the program.) It opened a command shell, ran a few commands, and then prompted for a password:

$ ~ boot2docker up<br>
2014/06/20 10:19:16 Waiting for VM to be started...<br>
...........docker@localhost's password:

Every password I tried was rejected. After some searching (using Google) to find the password I needed to use, I found this issue documented in a different GitHub project, boot2docker/boot2docker: “boot2docker up” asking for password #405:

<em>The command “boot2docker up” has been asking for a password</em>

Suggested fixes are:

• This means you’re running an old VM and need to upgrade it. Run “boot2docker delete” and “boot2docker init” to recreate the VM.

• Turns out the VM is old because the ISO is outdated. Run “boot2docker download” to get the latest ISO.

Really? I just downloaded and installed Docker. How is it running an old VM? Why did it download an old ISO? Anyway, I ran the delete, download, and init commands.

Success! Docker now started, and did so without asking me for a password.

Moral of the story: There’s an out-of-date Docker ISO that needs a password to run. If you see this problem, in a Windows command shell:

• run boot2docker delete to get rid of your VM

• run boot2docker download to get the latest ISO

• run boot2docker init to create a new VM

With this latest fix, Docker now ran successfully on my system. I got to the Docker prompt, where (as shown above) I ran the hello-world container and it worked!

Related topics

Some other posts on Docker and Bluemix:

• Bluemix Launches IBM Containers Beta Based on Docker

• Webinar: IBM Containers on Bluemix Based on Docker

• Managing Docker Containers on Bluemix from RHEL 6.6

• Announcing: Liberty profile on Docker Hub

• Introducing a Docker image for MQ Advanced for Developers

• Build and use Docker on the IBM POWER Linux platform

• Microservices Architecture, Containers and Docker