Docker on Windows

By Elton Stoneman
    What do you get with a Packt Subscription?

  • Instant access to this title and 7,500+ eBooks & Videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. Free Chapter
    Getting Started with Docker on Windows
About this book

Docker is a platform for running server applications in lightweight units called containers. You can run Docker on Windows Server 2016 and Windows 10, and run your existing apps in containers to get significant improvements in efficiency, security, and portability.

This book teaches you all you need to know about Docker on Windows, from 101 to deploying highly-available workloads in production. This book takes you on a Docker journey, starting with the key concepts and simple examples of how to run .NET Framework and .NET Core apps in Windows Docker containers. Then it moves on to more complex examples—using Docker to modernize the architecture and development of traditional ASP.NET and SQL Server apps.

The examples show you how to break up monoliths into distributed apps and deploy them to a clustered environment in the cloud, using the exact same artifacts you use to run them locally. To help you move confidently to production, it then explains Docker security, and the management and support options.

The book finishes with guidance on getting started with Docker in your own projects, together with some real-world case studies for Docker implementations, from small-scale on-premises apps to very large-scale apps running on Azure.

Publication date:
July 2017


Chapter 1. Getting Started with Docker on Windows

Docker is an application platform. It's a new way of running applications in isolated, lightweight units called containers. Containers are a very efficient way of running apps - they start in seconds, and the container doesn't add any overhead to the memory and compute requirements of the app. Docker is completely agnostic to the type of apps it can run. You can run a brand new .NET Core app in one container and a 10-year old ASP.NET 2.0 WebForms app in another container on the same server.

Containers are isolated units, but they can integrate with other components. Your WebForms container can access a REST API hosted in your .NET Core container. Your .NET Core container can access a SQL Server database running in a container or a SQL Server instance running on a separate machine. You can even set up a cluster with a mixture of Linux and Windows machines all running Docker, and have Windows containers transparently communicate with Linux containers.

Companies big and small are moving to Docker to take advantage of this flexibility and efficiency. The case studies from Docker, Inc. - the company behind the Docker platform - show that you can reduce your hardware requirements by 50% when you move to Docker, while still supporting high availability for your applications. These significant reductions apply equally to on-premises data centers and to the cloud.

Efficiency isn't the only gain. When you package your application to run in Docker, you get portability. You can run your app in a Docker container on your laptop, and it will behave in exactly the same way on a server in your data center and on a virtual machine (VM) in any cloud. This means your deployment process is simple and risk-free because you're deploying the exact same artifacts that you've tested, and you're also free to choose between hardware vendors and cloud providers.

The other big motivator is security. Containers add secure isolation between applications, so you can be confident that if one application is compromised, the attacker can't move on to compromise other apps on the same host. There are wider security benefits in the platform too. Docker can scan the contents of packaged applications and alert you to security vulnerabilities in your application stack. And you can digitally sign packages and configure Docker to run containers only from package authors that you trust.

Docker is built from open source components and is shipped as Docker Community Edition (Docker CE) and Docker Enterprise Edition (Docker EE). Docker CE is free to use and has monthly releases. Docker EE is a paid subscription, it comes with extended features and support and has quarterly releases. Docker CE and Docker EE are available on Windows, and both versions use the same underlying platform, so you can run your apps in containers on Docker CE and EE in the same way.


Docker and Windows containers

Docker originally ran on Linux, taking advantage of core Linux features but making it simple and efficient to use containers for application workloads. Microsoft saw the potential and worked closely with the Docker engineering team to bring the same functionality to Windows. Windows Server 2016 and Windows 10 are the first versions of Windows that can run Docker containers. Right now, you can run only Windows containers on Windows, but Microsoft is adding support for Linux containers to run on Windows too.

There is no integration between containers and the Windows UI, though. Containers are only for server side applications - workloads like websites, APIs, databases, message queues, message handlers, and console applications. You can't use Docker to run a client app, like a .NET WinForms or WPF application, but you could use Docker to package and distribute the application, which would give you a consistent build and release process for all your apps.

There is also a distinction between how containers run on Windows Server 2016 and Windows 10. The user experience for working with Docker is the same, but the way containers are hosted is different. On Windows Server, the process that serves your application actually runs on the server, and there's no layer between the container and the host. In the container, you may see w3wp.exe running to serve a website, but that process is actually running on the server - if you had ten web containers running, you would see ten instances of w3wp.exe in task manager on the server.

Windows 10 doesn't have the same operating system kernel as Windows Server 2016, so in order to provide containers with the Windows Server kernel, Windows 10 runs each container in a very light VM. These are called Hyper-V containers, and if you run a web app in a container on Windows 10, you won't see w3wp.exe running on the host - it's actually running inside a dedicated Windows Server kernel in the Hyper-V container.

It's good to understand this distinction. You use the same Docker artifacts and the same Docker commands on Windows 10 and Windows Server 2016, so the processes are the same, but there is a slight performance hit in using Hyper-V containers on Windows 10. Later in this chapter, I'll show you the options for running Docker on Windows, and you can choose the best approach for you.

Windows licensing

Windows containers don't have the same licensing requirements as servers or VMs running Windows. Windows is licensed at the host level, not the container level. If you have 100 Windows containers running on one server, you only need a license for the server. There are considerable savings to be had if you currently use VMs to isolate application workloads. Removing the VM layer and running apps in containers directly on the server removes the licensing requirement for all the VMs.

Hyper-V containers have separate licensing. On Windows 10, you can run multiple containers, but not for production deployments. On Windows Server, you can also run containers in Hyper-V mode to get increased isolation. This can be useful in multi-tenant scenarios, where you need to expect and mitigate for hostile workloads. Hyper-V containers are separately licensed, but in a high-volume environment, you would use a Datacenter license run Hyper-V containers without individual licenses.

Microsoft and Docker, Inc. have partnered to provide Docker EE at no cost with Windows Server 2016. The price of the Windows Server license includes Docker EE Basic, which gives you support to run applications in containers. If you have problems with a container or with the Docker service, you can raise it with Microsoft and they can go on to escalate it to Docker engineers.


Understanding the key Docker concepts

Docker is a very powerful but very simple application platform. You can get started with running your existing apps in Docker in just a few days, and be ready to move to production in a few days more. This book will take you through lots of examples of .NET Framework and .NET Core applications, running in Docker. You'll learn how to build, ship, and run applications in Docker and move on to advanced topics like solution design, security, administration, instrumentation, and continuous integration and continuous delivery (CI/CD).

To start with, you need to understand the core Docker concepts: images, registries, containers, and swarms--and understand how Docker actually runs.

The Docker service and Docker command-line

Docker runs as a background Windows service. This service manages all the running containers and exposes a REST API for consumers to work with containers and other Docker resources. The main consumer of that API is the Docker command-line tool, which is what I use for most of the code samples in this book.

The Docker REST API is public, and there are alternative management tools that are powered by the API, like Portainer (which is open source) and Docker Universal Control Plane (UCP) (which is a commercial product). The Docker CLI is very simple to use; you use commands like docker container run to run an application in a container and docker container rm to remove a container.

You can also configure the Docker API to be remotely accessible and configure your Docker CLI to connect to a remote service. This means you can manage a Docker host running in the cloud using Docker commands on your laptop. The setup to allow remote access should also include encryption, so your connection is secure--and in this chapter, I will show you an easy way to configure that.

When you have Docker running, you'll start by running containers from images.

Docker images

A Docker image is a complete application package. It contains one application and all of its dependencies, the language runtime, the application host, and the underlying operating system. Logically, the image is a single file, and it's a portable unit—you can share your application by pushing your image to a Docker registry. Anyone who has access can pull that image themselves and run your application in a container. It will behave in exactly the same way for them as it does for you.

Here's a concrete example. An ASP.NET WebForms app is going to run on Internet Information Services (IIS) in Windows Server. To package that application in Docker, you build an image that is based on Windows Server Core, add IIS, add ASP.NET, copy your application, and configure it as a website in IIS. You describe all these steps in a simple script called a Dockerfile, and you can use PowerShell or batch files for each step you need to perform.

You build the image by running docker image build. The input is the Dockerfile and any resources that need to be packaged into the image (like the web application content). The output is a Docker image. In this case, the image will have a logical size of about 11 GB, but 10 GB of that is the Windows Server Core image you're using as a base, and that image can be shared as the base across many other images (I will cover image layers and caching more in Chapter 4, Pushing and Pulling Images from Docker Registries).

The Docker image is like a snapshot of the filesystem for one version of your application. The image is static, and you distribute it using a registry.

Image registries

A registry is a storage server for Docker images. Registries can be public or private, and there are free public registries and commercial registry servers that allow fine-grained access control for images. Images are stored with a unique name within the registry. Anyone with access can upload an image by running docker image push and download an image by running docker image pull.

The most popular registries are the public ones hosted by Docker:

  • Docker Hub is the original registry, which has become hugely popular for open source projects in the Linux ecosystem. It has over 600,000 images stored and has hosted over 12 billion image pulls.
  • Docker Cloud is where you store images you build yourself, and you can configure images to be public or private. It's suitable for internal products, where you can limit access to the images. You can set up Docker Cloud to automatically build images from Dockerfiles stored in GitHub—currently, this is supported only for Linux-based images, but Windows support is coming soon.
  • Docker Store is where you get commercial software, pre-packaged as Docker images. Vendors are increasingly supporting Docker as a platform for their own applications, and you will find software from Microsoft, Oracle, HPE, and more on Docker Store.

In a typical workflow, you might build images as part of a CI pipeline and push them to a registry if all the tests pass. The image is then available for other users to run your application in a container.

Docker containers

A container is an instance of an application created from an image. The image contains the whole application stack, and it also specifies the process to start the application, so Docker knows what to do when you run a container. You can run multiple containers from the same image, and you can run containers in different ways (I describe them all in the next chapter). You start your application with docker container run, specifying the name of the image and your configuration options. Distribution is built into the Docker platform, so if you don't have a copy of the image on the host where you're trying to run the container, Docker will pull the image first. Then it starts the specified process, and your app is running in a container.

Containers don't need a fixed allocation of CPU or memory, and the processes for your application can use as much of the host's compute power as they need. You can run dozens of containers on modest hardware, and unless the applications all try and use a lot of CPU at the same time, they will happily run concurrently. You can also start containers with resource limits to restrict how much CPU and memory they have access to.

Docker provides the container runtime as well as image packaging and distribution. In a small environment and in development, you will manage individual containers on a single Docker host, which would be your laptop or a test server. When you move to production, you'll need high availability and the option to scale, and that comes with Docker swarm.

Docker swarm

Docker has the ability to run on a single machine or as one node in a cluster of machines all running Docker. This cluster is called a swarm, and you don't need to install anything extra to run in swarm mode. You install Docker on a set of machines, and on the first you run docker swarm init to initialize the swarm, and on the others you run docker swarm join to join the swarm.

I will cover swarm mode in depth in Chapter 7, Orchestrating Distributed Solutions with Docker Swarm, but it's important to know before you get much further that the Docker platform has high availability, scale, and resilience built in. Your Docker journey will hopefully lead you to production, where you'll need all these attributes.

In swarm mode Docker uses exactly the same artifacts, so you can run your app across 50 containers in a 20-node swarm, and the functionality will be the same as when you run it in a single container on your laptop. On the swarm, your app is more performant and tolerant of failure, and you'll be able to perform automated rolling updates to new versions.

Nodes in a swarm use secure encryption for all communication, using trusted certificates for each node. You can store application secrets as encrypted data in the swarm too, so database connection strings and API keys can be saved securely, and the swarm will deliver them only to containers that need them.

Docker is an established platform. It's new to Windows Server 2016, but it arrived on Windows after four years of releases on Linux. Docker is written in Go, which is a cross-platform language, and only a minority of code is specific to Windows. When you run Docker on Windows, you're running an application platform that has had years of successful production use.


Running Docker on Windows

It's easy to install Docker on Windows 10 and Windows Server 2016. On these operating systems, you can use the Docker for Windows installer, which sets up all the prerequisites, deploys the latest version of Docker CE, and gives you some useful options to manage image repositories and remote swarms with Docker Cloud.

In production, you should ideally use Windows Server 2016 Core, the installation with no UI. This reduces the attack surface and the amount of Windows updates your server will need. If you move all your apps to Docker, you won't need any other Windows features installed; you'll just have Docker EE running as a Windows service.

I'll walk through both these installation options and show you a third option using a VM in Azure, which is useful if you want to try Docker but don't have access to Windows 10 or Windows Server 2016.


There is a fantastic online Docker playground at Windows support is currently in beta, and it's a great way to try Docker without having to make any investment - you just browse the site and get started.

Docker for Windows

Docker for Windows is available from Docker Store—navigate to You can choose between the Stable channel and the Edge channel. Both channels give you Docker CE, but the Edge channel follows the monthly release cycle, and you will get experimental features. The Stable channel follows the EE release cycle, with quarterly updates.


You should use the Edge channel in development if you want to work with the latest features. In test and production, you will use Docker EE, so you need to be careful that you don't use features in development that are not yet available in EE.

Download and run the installer. The installer will verify that you can run Docker in your setup and will configure the Windows features needed to support Docker. When Docker is running, you will see a whale icon in the notification bar, which you can click on for options:

You need to select Switch to Windows containers before you do anything else. Docker for Windows can run Linux containers by running Docker inside a Linux VM on your machine. That's great to test out Linux apps to see how they run in containers, but this book is all about Windows containers - switch over, and Docker will remember that setting in future.

While Docker for Windows is running, you can open Command Prompt or a PowerShell session and start working with containers. First, verify that everything is working as expected by running docker version. You should see output similar to this:

> docker version

 Version: 17.06.0-ce
 API version: 1.30
 Go version: go1.8.3
 Git commit: 02c1d87
 Built: Fri Jun 23 21:30:30 2017
 OS/Arch: windows/amd64

 Version: 17.06.0-ce
 API version: 1.30 (minimum version 1.24)
 Go version: go1.8.3
 Git commit: 02c1d87
 Built: Fri Jun 23 22:19:00 2017
 OS/Arch: windows/amd64
 Experimental: true


The output tells you the version of the command-line client and the Docker service. The operating system field should read Windows for both; if not, then you may be in Linux mode, and you'll need to switch to Windows containers.

Now run a simple container:

docker container run dockeronwindows/ch01-whale

This uses a public image on Docker Cloud—one of the sample images for this book, which Docker will pull the first time you use it. If you don't have any other images, this will take few minutes, as it will also download the Microsoft Nano Server image that my image uses as a base. When the container runs, it shows some ASCII art and then exits. Run the same command again, and you will see that it executes much more quickly as the images are now cached locally.

That's all the setup you need. Docker for Windows also contains the Docker Compose tool I'll be using later in the book, so you're all set to follow along with the code samples.

Docker as a Windows Service

You can use Docker for Windows on Windows 10 and Windows Server 2016, and it's great for development and test environments. For production environments where you have a headless server with no UI, you can install Docker using a PowerShell module.

On a new installation of Windows Server 2016 core, use the sconfig tool to install all the latest Windows updates, and then run these PowerShell commands:

Install-Module -Name DockerMsftProvider -Repository PSGallery -Force
Install-Package -Name docker -ProviderName DockerMsftProvider

This will configure the server with the necessary Windows features, install Docker, and set it up to run as a Windows service. Depending on how many Windows updates were installed, you may need to reboot the server:

Restart-Computer -Force

When the server is online, check whether Docker is running with docker version, and then try to run a container from the sample image for this chapter:

docker container run dockeronwindows/ch01-whale

I use this configuration for some of my environments—running Windows Server 2016 Core in a lightweight VM, which has only Docker installed. You can use Docker on the server by connecting with Remote Desktop, or you can configure the Docker service to allow remote connections. This is a more advanced setup, but it does give you secure remote access.

It's best to set up the Docker service so that communication with the client is secured using TLS. Clients can connect only if they have the right TLS certificates to authenticate with the service. You can set this up by running these PowerShell commands inside the VM, supplying the VM's external IP address:

$ipAddress = '<vm-ip-address>'

mkdir -p C:\certs\client

docker container run --rm `
 --env SERVER_NAME=$(hostname) `
 --env IP_ADDRESSES=,$vm-ip-address `
 --volume 'C:\ProgramData\docker:C:\ProgramData\docker' `
 --volume 'C:\certs\client:C:\Users\ContainerAdministrator\.docker' `

Restart-Service docker


Don't worry too much about what this command is doing. Over the next few chapters, you'll get a good understanding of all these Docker options. I'm using a Docker image from Stefan Scherer, who is a Microsoft MVP and Docker Captain. The image has a script that secures the Docker service with TLS certificates. You can read more details on Stefan's blog at

When this command completes, it will have configured the Docker service to allow only secure remote connections and will also have created the certificates that the client needs to use to connect. Copy these certificates from C:\certs\client on the VM onto the machine where you want to use the Docker client.

On the client machine, you can set environment variables to point the Docker client to use a remote Docker service. These commands will set up a remote connection to the VM (assuming you have used the same path for the certificate files on the client):

$ipAddress = '<vm-ip-address>'


You can use this approach to securely connect to any remote Docker service. If you don't have access to Windows 10 or Windows Server 2016, you can create a VM on the cloud and connect to it using the same commands.

Docker in an Azure VM

Microsoft makes it easy to run Docker in Azure. They provide a VM image with Docker installed and configured and with the base Windows images already pulled so you can get started quickly.

For testing and exploring, I always use DevTest labs in Azure. It's a great feature for non-production environments. By default, any VMs you create in a DevTest lab will be turned off every evening, so you don't end up with a big Azure bill from a VM you used for a few hours and forgot to turn off.

You can create a DevTest Lab through the Azure Portal and then create a VM from Microsoft's VM image Windows Server 2016 Datacenter - with Containers. As an alternative to the Azure Portal, you can use the az command-line to manage the DevTest lab. I've packaged az in a Docker image, which you can run in a Windows container:

docker run -it dockeronwindows/ch01-az

This runs an interactive Docker container that has the az command packaged and ready to use. Run az login, and you'll need to open a browser and authenticate the Azure CLI. Then, you can run this in the container to create a VM:

az lab vm create `
 --lab-name docker-on-win --resource-group docker-on-winRG236992 `
 --name dow-vm-01 `
 --image 'Windows Server 2016 Datacenter - with Containers' `
 --image-type gallery --size Standard_DS2 `
 --admin-username 'elton' --admin-password 'S3crett20!7'

The VM uses the full Windows Server 2016 installation with the UI, so you can connect to the machine with RDP, open a PowerShell cmdlet, and start using Docker right away. Just like the other options, you can check whether Docker is running with docker version and then run a container from the sample image for this chapter:

docker container run dockeronwindows/ch01-whale

If an Azure VM is your preferred option, you can follow the steps from the previous section to secure the Docker API for remote access. This way, you can run the Docker command-line on your laptop to manage containers on the cloud.


Learning Docker with this book

Every code listing in this book is accompanied by a full code sample on my GitHub repository at The source tree is organized into a folder for each chapter, and for each chapter there's a folder for each code sample. In this chapter, I've used two samples to create Docker images, which you'll find in ch01\ch01-whale and ch01\ch01-az.


The code listings in the book may be condensed for the page, but the full code is always in the GitHub repository.

I prefer to follow along with the code samples when I'm learning a new technology, but if you want to use working versions of the demo applications, every sample is also available as a public Docker image on Docker Cloud. Wherever you see a docker container run command, the image already exists on Docker Cloud, so you can use mine rather than building your own if you wish. All the images in the dockeronwindows organization, such as this chapter's dockeronwindows/ch01-whale—were built from the relevant Dockerfile in the GitHub repository.

My own development environment is based on Windows Server 2016, where I use Docker for Windows. My test environment is based on Windows Server 2016 Core, where I run Docker as a Windows Service. I've also verified all the code samples using Windows 10.

I'm using version 17.06 of Docker, which is the latest release at the time of writing. Some of the features I demonstrate need version 17.06 as a minimum--such as multi-stage builds and secrets. But Docker has always been backward-compatible, so if you're using a version later than 17.06, then the sample Dockerfiles and images should work in the same way.

My goal is for this to be a definitive book about Docker on Windows, so I've covered everything from the 101 on containers through modernizing .NET apps with Docker and the security implications of containers to CI/CD and administration in production. The book ends with a guide to moving forward with Docker in your own projects.


If you want to discuss the book or your own Docker journey with me, feel free to ping me on Twitter at @EltonStoneman.



In this chapter I introduced Docker, an application platform that can run new and old apps in lightweight units of compute called containers. Companies are moving to Docker for efficiency, security, and portability. I covered:

  • How Docker works on Windows and how containers are licensed
  • The key Docker concepts: images, registries, containers, and swarms
  • The options to run Docker on Windows 10, Windows Server 2016, and Azure

If you're planning to work along with the code samples in the rest of the book, you should have a working Docker environment by now. In Chapter 2,Packaging and Running Applications as Docker Containers, I'll move on to packaging more complex apps as Docker images and showing how to manage state in containers with Docker volumes.

About the Author
  • Elton Stoneman

    Elton Stoneman has been a Microsoft MVP since 2010 and a Pluralsight author since 2013. Before joining Docker he spent 15 years as a consultant, architecting and delivering large and successful solutions built on .NET and powered by Windows, Docker, and Azure.

    He's enjoying working with the new evolution of Microsoft stack, helping people understand the great opportunities to modernize existing .NET Framework apps with Docker, and run them alongside new .NET Core apps in Windows and Linux containers.

    He blogs, tweets, teaches and speaks about Docker all the time. He is a regular at Docker and .NET user groups and he's had great fun speaking at conferences around the world, including DockerCon, NDC, DevSum, BuildStuff, WinOps, and Techorama.

    Browse publications by this author
Latest Reviews (7 reviews total)
I haven't finished yet but its a good walkthrough on using Docker on my Win 10 computer
very good very good very good
The book material is first class, but the quality of the actual book itself is extremely poor (more than 20 pages just fell out). Packt’s customer service response to this was dismissive and unhelpful.
Docker on Windows
Unlock this book and the full library FREE for 7 days
Start now