🔒 EXCLUSIVE: Engine/swarm/stack deploy - HD Photos!

When running Docker Engine in swarm mode, you can use docker stack deploy to deploy a complete application stack to the swarm. The deploy command accepts a stack description in the form of a Compose file.

Note

The docker stack deploy command uses the legacy Compose file version 3 format, used by Compose V1. The latest format, defined by the Compose specification isn't compatible with the docker stack deploy command.

For more information about the evolution of Compose, see History of Compose.

To run through this tutorial, you need:

1. A Docker Engine running in Swarm mode. If you're not familiar with Swarm mode, you might want to read Swarm mode key concepts and How services work.

   Note

   If you're trying things out on a local development environment, you can put your engine into Swarm mode with docker swarm init.

   If you've already got a multi-node swarm running, keep in mind that all docker stack and docker service commands must be run from a manager node.

2. A current version of Docker Compose.

Set up a Docker registry

Because a swarm consists of multiple Docker Engines, a registry is required to distribute images to all of them. You can use the Docker Hub or maintain your own. Here's how to create a throwaway registry, which you can discard afterward.

1. Start the registry as a service on your swarm:

2. Check its status with docker service ls:

   Once it reads 1/1 under REPLICAS, it's running. If it reads 0/1, it's probably still pulling the image.

3. Check that it's working with curl:

Create the example application

The app used in this guide is based on the hit counter app in the Get started with Docker Compose guide. It consists of a Python app which maintains a counter in a Redis instance and increments the counter whenever you visit it.

1. Create a directory for the project:

2. Create a file called app.py in the project directory and paste this in:

3. Create a file called requirements.txt and paste these two lines in:

4. Create a file called Dockerfile and paste this in:

5. Create a file called compose.yaml and paste this in:

   The image for the web app is built using the Dockerfile defined above. It's also tagged with 127.0.0.1:5000 - the address of the registry created earlier. This is important when distributing the app to the swarm.

Test the app with Compose

1. Start the app with docker compose up. This builds the web app image, pulls the Redis image if you don't already have it, and creates two containers.

   You see a warning about the Engine being in swarm mode. This is because Compose doesn't take advantage of swarm mode, and deploys everything to a single node. You can safely ignore this.

2. Check that the app is running with docker compose ps:

   You can test the app with curl:

3. Bring the app down:

Push the generated image to the registry

To distribute the web app's image across the swarm, it needs to be pushed to the registry you set up earlier. With Compose, this is very simple:

The stack is now ready to be deployed.

Deploy the stack to the swarm

1. Create the stack with docker stack deploy:

   The last argument is a name for the stack. Each network, volume and service name is prefixed with the stack name.

2. Check that it's running with docker stack services stackdemo:

   Once it's running, you should see 1/1 under REPLICAS for both services. This might take some time if you have a multi-node swarm, as images need to be pulled.

   As before, you can test the app with curl:

   With Docker's built-in routing mesh, you can access any node in the swarm on port 8000 and get routed to the app:

3. Bring the stack down with docker stack rm:

4. Bring the registry down with docker service rm:

5. If you're just testing things out on a local machine and want to bring your Docker Engine out of Swarm mode, use docker swarm leave: