Getting Started with Docker Desktop for Windows

The easiest way to create containerized applications and leverage the Docker Platform from your desktop


Thank you for installing Docker Desktop. Here is a quick 5 step tutorial on how to use. We will walk you through:

  • Running your first container
  • Creating and sharing your first Docker image and pushing it to Docker Hub
  • Create your first multi-container application
  • Learning Orchestration and Scaling with Docker Swarm and Kubernetes

Step 1: Local Web Server

Run IIS without setting it up

If you haven’t run Docker before, here’s a quick way to see the power of Docker at work. First, make sure you are using Windows Containers. Then from the command line, type

docker container run --detach --publish 8080:80 
--name web microsoft/iis:nanoserver

Then open http://localhost:8080 in your browser and see the default IIS web page. You can replace the default page with your own content by copying a file into the container. You need to stop the container first:

docker container stop web

Next, in your favorite text editor, create a file called index.html in a new directory. Something as simple as

<html><body><h1>Hello World!</h1></body></html>

in C:\temp.


Copy that file into the container and it will overwrite the default IIS homepage:

docker container cp C:\temp\index.html

Start the container again:

docker container start web

Refresh http://localhost:8080 and see your new content. You have created a web server without installing the web server. Docker took care of the dependencies.

When you’re finished, it’s good practice to stop and remove the running containers

docker container stop web
docker container rm web

Step 2: Customize and Push to Docker Hub

The last step used a Docker image which Microsoft publishes and maintains. Next step, create your own custom image. You should have a Docker ID, you probably created it to download Docker Desktop.

In your favorite text editor create a file called Dockerfile in the same C:\temp directory. No extension, just Dockerfile. Paste in this code and save the file:

FROM microsoft/iis:nanoserver
COPY index.html /inetpub/wwwroot

This tells Docker to use the same IIS base image, and create a layer that adds in the HTML you created in the last step. Instead of manually copying a file into the container, you will create an image with your HTML already inside it. To build the image, in your terminal, type:

docker image build --tag <YourDockerID>/firstimage .

Two things, first replace <YourDockerID> with your Docker ID. Also notice the “.” at the end of the line. That tells Docker to build in the context of this directory. So when it looks to COPY the file to /inetpub/wwwroot it will use the file from this directory.

You can run it:

docker container run --detach --publish 8081:80 
--name web2  <YourDockerID>/firstimage

And go to http://localhost:8081 to see the page - note your original container is still running and you can see it at http://localhost:8080.

Finally push to Docker Hub:

docker image push <YourDockerID>/firstimage

You may be asked to login if you haven’t already. Then you can go to, login and check your repositories

Finally, stop and remove the running containers:

docker container stop web2
docker container rm web2

Step 3: Run a Multi-Service App

Easily connect multiple services together

Docker Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration. Docker Compose installs automatically with Docker Desktop.

A multi-container app is an app that has multiple containers running and communicating with each other. This sample uses a simple .Net Core web app running with a MySQL database. You can check out the app in our dockersamples GitHub repo. We’ve pushed two images to the Docker Hub under the dockersamples repo. Docker Compose handles service discovery directly, allowing the app to reference the service directly and Docker will route traffic to the right container. To try it out, open a text editor and paste the text from this file. Then save it as docker-compose.yml.

There’s a lot of details in there but basically you can see that it specifies the images to be used, the service names, application configuration, the ports available, and networks the different services are on.

To run it, open a command line and navigate to the same directory as the docker-compose.yml file. At the command line, type

docker-compose up -d

You will see a bunch of commands go by as it pulls images from Docker Hub and then starts them up. When it has finished running, navigate to http://localhost. You should see a music album viewer. The .NET Core application saves data in the MySQL database - you don’t need .NET Core or MySQL installed, all the components are running in Docker.

To stop and remove all services and resources created by Docker Compose:

docker-compose down

Step 4: Orchestration: Swarm

Before you start this section, make sure you’re using Linux containers. Swarm does support Windows containers, but they are much bigger and will take longer to pull.

While it is easy to run an application in isolation on a single machine, orchestration allows you to coordinate multiple machines to manage an application, with features like replication, encryption, load balancing, service discovery and more. If you've read anything about Docker, you have probably heard of Kubernetes and Docker swarm mode. Docker Desktop is the easiest way to get started with either Swarm or Kubernetes.

A swarm is a group of machines that are running Docker and joined into a cluster. After that has happened, you continue to run the Docker commands you’re used to, but now they are executed on a cluster by a swarm manager. The machines in a swarm can be physical or virtual. After joining a swarm, they are referred to as nodes.

Swarm mode uses managers and workers to run your applications. Managers run the swarm cluster, making sure nodes can communicate with each other, allocate applications to different nodes, and handle a variety of other tasks in the cluster.

Swarm uses the Docker command line or the Docker Compose file format with a few additions. Give it a try with a few simple steps.

First, copy the contents of this file into a file called docker-stack-simple.yml.

Then, from the command line in the same directory as that file, type the following commands.

$ docker swarm init

You should see a command you could copy and paste to add another node to the swarm. For our purposes right now don’t add any more nodes to the swarm.

$ docker stack deploy -c docker-stack-simple.yml vote

Docker will tell you that it is creating networks and services. And all connected to a stack called “vote”. You can see all stacks running on your Swarm by typing

$ docker stack ls

Probably you have just the one, with 5 services. Next you can see all the services by typing

$ docker service ls

This will show you the 5 services, all with 1 replica. All with a name vote_ plus something like vote_db. You can run this a few times until all the replicas say 1/1.

So what happened? With the simple compose file format you created a application that has 5 components:

  1. A voting page in Flask that pushing results to redis.
  2. A redis instance to store key value pairs.
  3. A worker that goes into the redis instance, pulls out data and pushes it into the database.
  4. A postgres database.
  5. A results page running in Node.js that draws from the database.

Now, click on localhost:5000 to vote. You can vote for cats or dogs, whichever you like better. On localhost:5001 you can see the results of the vote. Open up different browsers to add in additional votes if you want.

The code for all these components is in our Example Voting App repo on GitHub. There’s a lot going on here but here are some points to highlight:

  1. The services all refer to each other by name. So when the result app calls on the database, it connects to `postgres@db` and the Swarm takes care of directory the service to `db`.
  2. In a multi-node environment, Swarm will spread out the replicas however you want.
  3. Swarm will also do basic load balancing. Here’s how you can see this in action:

Load localhost:5000 again. Note the “Processed by container ID “ at the bottom of the page. Now add a replica:

docker service scale vote_vote=3

Once it is done verifying, reload the page a few times and see the container ID rotates between three different values. Those are the three different containers. Even if they were on different nodes, they would share the same ingress and port.

To clean up before moving to the next section, type

$ docker stack rm vote

Step 5: Orchestration: Kubernetes

Before you start this section, make sure you’re using Linux containers. Kubernetes does not yet support Windows containers.

Kubernetes installation is easy with Docker Desktop. The first time you enable Kubernetes in the settings, it will install seamlessly. Directions are below.

Kubernetes deployments tend to be more complex than Docker Swarm, and there are many component types, including Pods, Deployments, Services, and more. You can find details over in the Kubernetes documentation, but follow directions here to deploy your first Kubernetes application locally.

We will use the Kubernetes Wordsmith Demo. Wordsmith is the demo project shown at DockerCon EU 2017, where Docker announced that support for Kubernetes was coming to the Docker platform.

The demo app runs across three containers:

db - a Postgres database which stores words
words - a Java REST API which serves words read 
from the database
web - a Go web application which calls the API 
and builds words into sentences.

First create remove your old docker-compose.yml file from C:\Temp, and replace it with the contents of this file. Also create a new file called kube-deployment.yml with the contents of this file. These files do the same thing, we’re going to show you how to use each in turn using Docker Desktop.

You can use docker-compose to pull pre-built images from Docker Hub using

docker-compose pull

Deploy as a Docker Stack

Docker lets you use the simple Docker Compose file format to deploy complex applications to Kubernetes. You can deploy the wordsmith app to the local Kubernetes cluster using docker-compose.yml.

First check whether Kubernetes is installed and running. Open up settings from the Docker Desktop menu and select Kubernetes. Make sure Enable Kubernetes is checked, and that Kubernetes is the default orchestrator for docker stack commands. If this is the first time you have enabled Kubernetes, it may take a little while to download and install.

Next, deploy the app to Kubernetes as a stack using the compose file:

docker stack deploy wordsmith -c docker-compose.yml

Docker Desktop includes the kubectl command line, so you can work directly with the Kube cluster. Check the services are up, and you should see output like this:

$ kubectl get svc

Check the pods are running, and you should see one pod each for the database and web components, and five pods for the words API - which is specified as the replica count in the compose file:

$ kubectl get pods

Then browse to http://localhost:8080 to see the site. Each time you refresh the page, you'll see a different sentence generated by the API calls.

Deploy Using a Kubernetes Manifest

You can deploy the same app to Kubernetes using the Kubernetes manifest. That describes the same application in terms of Kubernetes deployments, services and pod specifications.

First, remove the Kubernetes stack:

docker stack rm wordsmith

Alternatively, you can leave the Docker stack deployment running and create a second deployment in a new Kubernetes namespace.

Now apply the manifest using kubectl:

kubectl apply -f kube-deployment.yml

Now browse to http://localhost:8081 and you will see the same site.

To clean up once you’re done, type

$ kubectl delete -f kube-deployment.yml