Docker Windows Getting Started

Posted onby

Getting Started with Docker on Windows. Open a terminal and execute docker to verify that everything was installed correctly. If it was, you should see the list of commands below: Docker Pillars. OK, we’re on our way. Before we get too deep, It’s important to go over the big picture: what I refer to as the Docker Pillars. Knowing these will.

  1. Getting Started. Please be sure to review the Data Collection documentation in order to understand the deployment models, components, and repositories applicable to the OpenTelemetry Collector. The OpenTelemetry Collector consists of a single binary and two primary deployment methods.
  2. Install Docker for Windows – Stable channel. After installing Docker, logging out of Windows and re-login is required. Docker may prompt for that. After logging in again, Docker starts automatically. Switch Docker to use Windows Containers. By default, Docker is set to use Linux containers.
  3. This step-by-step guide will help you get started developing with remote containers by setting up Docker Desktop for Windows with WSL 2 (Windows Subsystem for Linux, version 2). Docker Desktop for Windows is available for free and provides a development environment for building, shipping, and running dockerized apps.

What is “swarm mode”?

Swarm mode is a Docker feature that provides built in container orchestration capabilities, including native clustering of Docker hosts and scheduling of container workloads. A group of Docker hosts form a “swarm” cluster when their Docker engines are running together in “swarm mode.” For additional context on swarm mode, refer to Docker's main documentation site.

Manager nodes and worker nodes

A swarm is composed of two types of container hosts: manager nodes, and worker nodes. Every swarm is initialized via a manager node, and all Docker CLI commands for controlling and monitoring a swarm must be executed from one of its manager nodes. Manager nodes can be thought of as “keepers” of the Swarm state—together, they form a consensus group that maintains awareness of the state of services running on the swarm, and it’s their job to ensure that the swarm’s actual state always matches its intended state, as defined by the developer or admin.



Any given swarm can have multiple manager nodes, but it must always have at least one.

Worker nodes are orchestrated by Docker swarm via manager nodes. To join a swarm, a worker node must use a “join token” that was generated by the manager node when the swarm was initialized. Worker nodes simply receive and execute tasks from manager nodes, and so they require (and possess) no awareness of the swarm state.

Swarm mode system requirements

At least one physical or virtual computer system (to use the full functionality of swarm at least two nodes is recommended) running either Windows 10 Creators Update or Windows Server 2016with all of the latest updates*, setup as a container host (see the topic, Windows containers on Windows 10 or Windows containers on Windows Server for more details on how to get started with Docker containers on Windows 10).

*Note: Docker Swarm on Windows Server 2016 requires KB4015217

Docker Engine v1.13.0 or later

Open ports: The following ports must be available on each host. On some systems, these ports are open by default.

  • TCP port 2377 for cluster management communications
  • TCP and UDP port 7946 for communication among nodes
  • UDP port 4789 for overlay network traffic

Initializing a Swarm cluster

To initialize a swarm, simply run the following command from one of your container hosts (replacing <HOSTIPADDRESS> with the local IPv4 address of your host machine):

When this command is run from a given container host, the Docker engine on that host begins running in swarm mode as a manager node.

Adding nodes to a swarm

Multiple nodes are not required to leverage swarm mode and overlay networking mode features. All swarm/overlay features can be used with a single host running in swarm mode (i.e. a manager node, put into swarm mode with the docker swarm init command).

Adding workers to a swarm

Once a swarm has been initialized from a manager node, other hosts can be added to the swarm as workers with another simple command:

Here, <MANAGERIPADDRESS> is the local IP address of a swarm manager node, and <WORKERJOINTOKEN> is the worker join-token provided as output by the docker swarm init command that was run from the manager node. The join-token can also be obtained by running one of the following commands from the manager node after the swarm has been initialized:

Adding managers to a swarm

Additional manager nodes can be added to a swarm cluster with the following command:

Again, <MANAGERIPADDRESS> is the local IP address of a swarm manager node. The join token, <MANAGERJOINTOKEN>, is a manager join-token for the swarm, which can be obtained by running one of the following commands from an existing manager node:

Creating an overlay network

Once a swarm cluster has been configured, overlay networks can be created on the swarm. An overlay network can be created by running the following command from a swarm manager node:

Here, <NETWORKNAME> is the name you'd like to give to your network.

Deploying services to a swarm

Once an overlay network has been created, services can be created and attached to the network. A service is created with the following syntax:

Here, <SERVICENAME> is the name you'd like to give to the service--this is the name you will use to reference the service via service discovery (which uses Docker's native DNS server). <NETWORKNAME> is the name of the network that you would like to connect this service to (for example, 'myOverlayNet'). <CONTAINERIMAGE> is the name of the container image that will defined the service.


The second argument to this command, --endpoint-mode dnsrr, is required to specify to the Docker engine that the DNS Round Robin policy will be used to balance network traffic across service container endpoints. Currently, DNS Round-Robin is the only load balancing strategy supported on Windows Server 2016.Routing mesh for Windows docker hosts is supported on Windows Server 2019 (and above), but not on Windows Server 2016. Users seeking an alternative load balancing strategy on Windows Server 2016 today can setup an external load balancer (e.g. NGINX) and use Swarm’s publish-port mode to expose container host ports over which to balance traffic.

Scaling a service

Once a service is deployed to a swarm cluster, the container instances composing that service are deployed across the cluster. By default, the number of container instances backing a service—the number of “replicas,” or “tasks” for a service—is one. However, a service can be created with multiple tasks using the --replicas option to the docker service create command, or by scaling the service after it has been created.

Service scalability is a key benefit offered by Docker Swarm, and it, too, can be leveraged with a single Docker command:

Here, <SERVICENAME> is the name of the service being scaled, and <REPLICAS> is the number of tasks, or container instances, to which the service is being scaled.

Viewing the swarm state

There are several useful commands for viewing the state of a swarm and the services running on the swarm.

List swarm nodes

Use the following command to see a list of the nodes currently joined to a swarm, including informaiton on the state of each node. This command must be run from a manager node.

In the output of this command, you will notice one of the nodes marked with an asterisk (*); the asterisk simply indicates the current node--the node from which the docker node ls command was run.

List networks

Use the following command to see a list of the networks that exist on a given node. To see overlay networks, this command must be run from a manager node running in swarm mode.

List services

Use the following command to see a list of the services currently running on a swarm, including information on their state.

List the container instances that define a service

Use the following command to see details on the container instances running for a given service. The output for this command includes the IDs and nodes upon which each container is running, as well as infromation on the state of the containers.

Linux+Windows mixed-OS clusters

Recently, a member of our team posted a short, three-part demo on how to set up a Windows+Linux mixed-OS application using Docker Swarm. It's a great place to get started if you're new to Docker Swarm, or to using it to run mixed-OS applications. Check it out now:

Initializing a Linux+Windows mixed-OS Cluster

Isl Naruto

Initializing a mixed-OS swarm cluster is easy--as long as your firewall rules are properly configured and your hosts have access to one another, all you need to add a Linux host to a swarm is the standard docker swarm join command:

You can also initialize a swarm from a Linux host using the same command that you would run if initializing the swarm from a Windows host:

Adding labels to swarm nodes

In order to launch a Docker Service to a mixed-OS swarm cluster, there must be a way to distinguish which swarm nodes are running the OS for which that service is designed, and which are not. Docker object labels provide a useful way to label nodes, so that services can be created and configured to run only on the nodes that match their OS.


Docker object labels can be used to apply metadata to a variety of Docker objects (including container images, containers, volumes and networks), and for a variety of purposes (e.g. labels could be used to separate 'front-end' and 'back-end' components of an application, by allowing front-end microservices to be secheduled only on 'front-end' labeled nodes and back-end mircoservices to be scheduled only on 'back-end' labeled nodes). In this case, we use labels on nodes, to distinguish Windows OS nodes and Linux OS nodes.

To label your existing swarm nodes, use the following syntax:

Here, <LABELNAME> is the name of the label you are creating--for example, in this case we are distinguishing nodes by their OS, so a logical name for the label could be, 'os'. <LABELVALUE> is the value of the label--in this case, you might choose to use the values 'windows' and 'linux'. (Of course, you may make any naming choices for your label and label values, as long as you remain consistent). <NODENAME> is the name of the node that you are labeling; you can remind yourself of the names of your nodes by running docker node ls.

For example, if you have four swarm nodes in your cluster, including two Windows nodes and two Linux nodes, your label update commands may look like this:

Deploying services to a Mixed-OS swarm

With labels for your swarm nodes, deploying services to your cluster is easy; simply use the --constraint option to the docker service create command:

For example, using the label and label value nomenclature from the example above, a set of service creation commands--one for a Windows-based service and one for a Linux-based service--might look like this:


Currently, swarm mode on Windows has the following limitations:

  • Data-plane encryption not supported (i.e. container-container traffic using the --opt encrypted option)
  • Routing mesh for Windows docker hosts is not supported on Windows Server 2016, but only from Windows Server 2019 onwards. Users seeking an alternative load balancing strategy today can setup an external load balancer (e.g. NGINX) and use Swarm’s publish-port mode to expose container host ports over which to load balance. More detail on this below.


For more details on how to setup Docker Swarm Routing Mesh, please see this blog post

Publish ports for service endpoints

Users seeking to publish ports for their service endpoints can do so today using either publish-port mode, or Docker Swarm's routing mesh feature.

To cause host ports to be published for each of the tasks/container endpoints that define a service, use the --publish mode=host,target=<CONTAINERPORT> argument to the docker service create command:

For example, the following command would create a service, 's1', for which each task will be exposed via container port 80 and a randomly selected host port.

After creating a service using publish-port mode, the service can be queried to view the port mapping for each service task:

The above command will return details on every container instance running for your service (across all of your swarm hosts). One column of the output, the “ports” column, will include port information for each host of the form <HOSTPORT>-><CONTAINERPORT>/tcp. The values of <HOSTPORT> will be different for each container instance, as each container is published on its own host port.

Tips & Insights

Existing transparent network can block swarm initialization/overlay network creation

On Windows, both the overlay and transparent network drivers require an external vSwitch to be bound to a (virtual) host network adapter. When an overlay network is created, a new switch is created then attached to an open network adapter. The transparent networking mode also uses a host network adapter. At the same time, any given network adapter can only be bound to one switch at a time--if a host has only one network adapter it can attach to only one external vSwitch at a time, whether that vSwitch be for an overlay network or for a transparent network.

Hence, if a container host has only one network adapter it is possible to run into the issue of a transparent network blocking creation of an overlay network (or vice-versa), because the transparent network is currently occupying the host's only virtual network interface.

There are two ways to get around this issue:

  • Option 1 - delete existing transparent network: Before initializing a swarm, ensure there is not an existing transparent network on your container host. Delete transparent networks to ensure there is a free virtual network adapter on your host to be used for overlay network creation.
  • Option 2 - create an additional (virtual) network adapter on your host: Instead of removing any transparent network that's on your host you can create an additional network adapter on your host to be used for overlay network creation. To do this, simply create a new external network adapter (using PowerShell or Hyper-V Manager); with the new interface in place, when your swarm is initialized the Host Network Service (HNS) will automatically recognize it on your host and use it to bind the external vSwitch for overlay network creation.

Estimated reading time: 4 minutes

Welcome! We are excited that you want to learn Docker.

This page contains step-by-step instructions on how to get started with Docker. In this tutorial, you’ll learn how to:

  • Build and run an image as a container
  • Share images using Docker Hub
  • Deploy Docker applications using multiple containers with a database
  • Running applications using Docker Compose

In addition, you’ll also learn about the best practices for building images, including instructions on how to scan your images for security vulnerabilities.

If you are looking for information on how to containerize an application using your favorite language, see Language-specific getting started guides.

We also recommend the video walkthrough from DockerCon 2020.

Download and install Docker

This tutorial assumes you have a current version of Docker installed on yourmachine. If you do not have Docker installed, choose your preferred operating system below to download Docker:

For Docker Desktop installation instructions, see Install Docker Desktop on Mac and Install Docker Desktop on Windows.

Start the tutorial

If you’ve already run the command to get started with the tutorial, congratulations! If not, open a command prompt or bash window, and run the command:

You’ll notice a few flags being used. Here’s some more info on them:

  • -d - run the container in detached mode (in the background)
  • -p 80:80 - map port 80 of the host to port 80 in the container
  • docker/getting-started - the image to use


You can combine single character flags to shorten the full command.As an example, the command above could be written as:

The Docker Dashboard

Before going too far, we want to highlight the Docker Dashboard, which givesyou a quick view of the containers running on your machine. The Docker Dashboard is available for Mac and Windows. It gives you quick access to container logs, lets you get a shell inside the container, and lets youeasily manage container lifecycle (stop, remove, etc.).

To access the dashboard, follow the instructions in theDocker Desktop manual. If you open the dashboardnow, you will see this tutorial running! The container name (jolly_bouman below) is arandomly created name. So, you’ll most likely have a different name.

What is a container?

Now that you’ve run a container, what is a container? Simply put, a container issimply another process on your machine that has been isolated from all other processeson the host machine. That isolation leverages kernel namespaces and cgroups, features that have been in Linux for a long time. Docker has worked to make these capabilities approachable and easy to use.

Creating containers from scratch

If you’d like to see how containers are built from scratch, Liz Rice from Aqua Securityhas a fantastic talk in which she creates a container from scratch in Go. While she makesa simple container, this talk doesn’t go into networking, using images for the filesystem, and more. But, it gives a fantastic deep dive into how things are working.

What is a container image?

When running a container, it uses an isolated filesystem. This custom filesystem is provided by a container image. Since the image contains the container’s filesystem, it must contain everything needed to run an application - all dependencies, configuration, scripts, binaries, etc. The image also contains other configuration for the container, such as environment variables,a default command to run, and other metadata.

We’ll dive deeper into images later on, covering topics such as layering, best practices, and more.


If you’re familiar with chroot, think of a container as an extended version of chroot. Thefilesystem is simply coming from the image. But, a container adds additional isolation notavailable when simply using chroot.

Docker Windows Getting Started Menu

CLI references

Refer to the following topics for further documentation on all CLI commands used in this article:

get started, setup, orientation, quickstart, intro, concepts, containers, docker desktop