Avoid Traps when Getting Started with Docker on Windows

So you want to get started with Docker on Windows.  Like all your investigations, you search the web for Docker Windows.  This is where you can get mislead.  This article uncovers the costly pitfalls when following what seems to be the ‘easy’ path to using Docker in a Windows environment.

The Easy Path Will Cost You

Let’s start with the easy path.  Do a search for two words: Docker Windows.  If you used Google, the first result is likely to be “Docker for Windows“.  When you click on the link, you are brought to an official docker.com page.  They tout that Docker for Windows “is a native Windows app deeply integrated with Hyper-V virtualization, networking and file system, making it the fastest and most reliable Docker environment for Windows.”  Seems reasonable.  After all, they created Docker and should know what is best for your Windows, right?  You will see how these performance gains come at a financial cost while limiting the capabilities of your OS to leverage an open source VM engine.

Dose of Reality

Be prepared, however, to pay the piper by upgrading your Windows 10 Home to Windows 10 Professional.  The only mention of this is a footnote at the bottom of the page: “* Requires Microsoft Windows 10 Professional or Enterprise 64-bit“.  This means you’ll need the latest PC hardware and Windows OS to make use of Docker for Windows.  The footnote also mentions Docker Toolbox as an option which we’ll discuss later.

Making a Deal with the Devil

What if you already have Oracle VirtualBox installed and want to get Docker working on Windows.  If you choose Docker for Windows, you will get Microsoft Hyper V installed which is incompatible with VirtualBox.  The simple act of installing Docker for Windows will break VirtualBox so that any Virtual Machines that you have created with it will no longer work.  The reason is that Hyper V completely takes over the machine’s virtualization.  And what is even worse, if you try to back out by uninstalling Docker for Windows and re-installing VirtualBox, your system state will continue to prevent VirtualBox from working!  In other words, you have made a deal with the devil and now you can’t get out of it; at least, not without removing registry entries or better yet, restoring Windows to a known working state.

Avoiding the Trap: Use Docker Toolbox

There was a time prior to the Docker for Windows application when Docker Toolbox was the only game in town.  Docker Toolbox uses Oracle’s VirtualBox to create a small Linux VM with a running Docker Machine.  While this adds a little overhead, the benefit is being able to run Docker containers on older Windows as well as Windows 10 Home.  Included with Docker Toolbox is the Docker Quickstart Terminal which ensures that the VM and Docker Machine are started and then connects a terminal shell to your VM instance.

Docker on Windows Installation Options: In a Nutshell

FeatureDocker ToolboxDocker for Windows
OS CompatibilityWindows 7, 8, 10
64 bit only
Windows 10 Professional
Windows 10 Enterprise
64 bit only
Virtual Machine (VM) EngineOracle VirtualBoxMicrosoft Hyper V
VM IncompatibilityWon't work with Microsoft Hyper VWon't work with Oracle VirtualBox
PerformanceAdditional overhead due to running Docker within Linux in a VM.Claims less overhead because the VM is more integrated with Windows.


Docker Toolbox will work across more types of Windows systems that exist in the wild.  Many people utilize older machines and older versions of Windows in order to keep costs down.  Using Docker Toolbox will empower more users to learn Docker and experience the benefits of installing entire application suites to make the best use of their equipment.

Behavior Driven Testing

Developing software in most companies starts with a Product Owner who is responsible for identifying and communicating requirements to the Development team (including QA).  The process flow usually goes something like this:

A Product Owner (or Product Team)
-> Collects and writes Requirements in a prose format
-> Someone interprets and rewrites tasks for Development
-> Development implements the feature
-> Someone may even interpret and rewrite the requirements for QA
-> Per QA Plan’s Definition of Done, QA may write automated tests
-> When the feature is ready, QA executes tests
-> QA interprets results
-> QA either sends ticket back to Development to fix
-> QA generates a report for review.
-> When Definition of Done is met, the Product is released.

There are two areas in this process that have seen streamlining thanks to a number of open source technologies.  These areas are:

  • Improvements to the way a Product Owner formulates the requirements
  • Improvements to tools that automatically report and integrate with those requirements

Technology Stack

  • JIRA: Software project management tool
  • Xray for JIRA: Test Management tool for JIRA
  • Java + Groovy: Enables Domain Specific Language (DSL) creation and use.
  • Gradle: A Groovy DSL that simplifies building and running tests
  • Geb: A Groovy DSL that simplifies Selenium. Especially when you use the page object pattern.
  • Spock: A Groovy DSL that uses the Gherkin language for specifying behaviors (BDD) as an action and assertion combination. Similar to Cucumber except that the feature file information becomes the high level structure to contain the test details for implementing the behavior.

Sample Gherkin Specification

When user navigates to login page
And user enters valid user credentials
And user clicks on Login button
Then user is shown the home page

Spock can be used for framing unit, back-end, and integration testing. When combined with Geb, they can be used for UI and end-to-end workflow testing. The integration of Spock means that tests are aligned more closely with the Specifications (i.e. Requirements).

I’ve extended the test infrastructure with features so that each test will output results directly to JIRA tickets thanks to the Xray for JIRA plugin. The end result gives the Product Owner a better sense of confidence that the implemented feature capabilities have met the specifications.

Overview of the New and Improved Process

  • Product team writes easy to read user stories and scenarios (examples) using the Gherkin language. These acceptance tests are stored in JIRA as Xray tests.
  • Development and QA updates the scenarios (test cases) or adds new test cases.
  • As Development implements the features functionality, QA writes the detail to test the features functionality by utilizing the Gherkin scenario specification as an outline to each test.
  • When the implementation is ready from development, QA can utilize their automated test to verify functionality. QA becomes closely tied with Development by being in lock step.
  • Test results are sent back to JIRA and get reported within the ticket associated with each test; where the test results belong.