Sample app overviewEstimated reading time: 6 minutes
This example is built around a web-based voting application that collects, tallies, and returns the results of votes (for cats and dogs, or other choices you specify). The voting app includes several services, each one running in its own container. We’ll deploy the app as a stack to introduce some new concepts surfaced in Compose Version 3, and also use swarm mode, which is cluster management and orchestration capability built into Docker Engine.
If you haven’t yet downloaded Docker or installed it, go to Get Docker and grab Docker for your platform. You can follow along and run this example using Docker for Mac, Docker for Windows, Docker Toolbox, or Docker for Linux.
If you are totally new to Docker, you might want to work through the Get Started with Docker tutorial first, then come back here.
What you’ll learn and do
In this tutorial, you’ll learn how to:
docker machineto create multiple virtual local hosts or dockerized cloud servers
dockercommands to set up and run a swarm with manager and worker nodes
- Deploy the
voteapp services across the two nodes by feeding our example
docker-stack.ymlfile to the
docker stack deploycommand
- Test the app by voting for cats and dogs, and view the results
- Use the
visualizerto explore and understand the runtime app and services
- Update the
docker-stack.ymland redeploy the app using a different
voteimage to implement a poll on different choices
- Use features new in Compose Version 3, highlighted in the sample app
Preview of voting app stack and how it works
These next few topics provide a quick tour of the services, deployment configuration, files, and commands we will use.
This diagram represents the application stack at runtime. It shows dependencies among the services, and a potential division of services between the manager and worker nodes in a swarm. As you’ll discover in the tutorial, some services are constrained to always run on a manager node, while others can run on either a manager or workers, at the discretion of swarm load balancing.
Services and images overview
A service is a bit of executable code
designed to accomplish a specific task. A service can run in one or more
containers. Defining a service configuration for your app (above and beyond
docker run commands in a Dockerfile) enables you to deploy the app to a swarm
and manage it as a distributed, multi-container application.
|Service||Description||Base Image on Docker Hub|
||Displays the web page where you cast your vote at
||Based on a Python image, dockersamples/examplevotingapp_vote|
||Shows the voting results in a web browser at
||Based on a Node.js image, dockersamples/examplevotingapp_result|
||Shows a realtime map of services deployed across the available nodes, viewable at
||Based on a Node.js image, dockersamples/visualizer|
||Collects raw voting data and stores it in a key/value queue||Based on the Alpine version of the official
||A PostgreSQL service which provides permanent storage on a host volume||Based on the official
||A background service that transfers votes from the queue to permanent storage||Based on a .NET image, dockersamples/examplevotingapp_worker|
Each service will run in its own container. Using swarm mode, we can also scale the application to deploy replicas of containerized services distributed across multiple nodes.
docker-stack.yml deployment configuration file
In the Getting Started with Docker tutorial, you wrote a Dockerfile for the whalesay app then used it to build a single image and run it as a single container.
For this tutorial, the images are pre-built, and we use a stack file instead of a Dockerfile to specify the images. When we deploy, each image will run as a service in a container (or in multiple containers, for those that have replicas defined to scale the app).
To follow along, you need only have Docker running and a copy of the
file that we provide.
This file defines all the services we want to use along with details about how and where those services will run; their base images, configuration details such as ports, networks, volumes, application dependencies, and the swarm configuration.
This example snip-it taken from our
docker-stack.yml shows one of the
services fully defined. (The full file is
vote: image: dockersamples/examplevotingapp_vote:before ports: - 5000:80 networks: - frontend depends_on: - redis deploy: replicas: 2 update_config: parallelism: 2 restart_policy: condition: on-failure
The image key defines which image the service will use. The
dockersamples/examplevotingapp_vote:before. This specifies the path to the image on Docker Hub (as shown in the table above), and an image tag,
beforeto indicate the version of the image we want to start with. In the second part of the tutorial, we will edit this file to call a different verson of this image with an
The depends_on key allows you to specify that a service is only deployed after another service. In our example,
voteonly deploys after
The deploy key specifies aspects of a swarm deployment. For example, in this configuration we create replicas of the
voteservice (2 containers for
votewill be deployed to the swarm). The
resultservice, not shown in the file snip-it above, will also have 2 replicas. Additionally, we will use the
deploykey to constrain some other services (
visualizer) to run only on a manager node.
docker stack deploy command
To deploy the voting app, we will run the
deploy command with appropriate
options, using the configuration in our
docker-stack.yml file to pull the
referenced images and launch the services in a swarm.
Where to learn more
If you are interested in reading more about Compose version 3.x, stack files, Docker Engine 1.13.x, swarm mode integration, Docker CE, or Docker EE, jump to the list of resources at the end of this tutorial.
Ready to get started? In the next step, we’ll set up two Dockerized hosts.