Installing Docker: Fixes for common problems
8 min read
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:
-
Boot2Docker Start shortcut doesn’t work – the Boot2Docker Start shortcut doesn’t run the
start.sh
script 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. -
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:
That simple program responds with “Hello from Docker. This message shows that your installation appears to be working correctly.” The output looks like this:
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:
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:
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 bin
directory 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:
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:
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: