Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 38 ยท Stacks and Deployment

Compose Files for Docker Swarm Stacks

Write a Compose file that docker stack deploy understands: services, networks, volumes, secrets and configs, which keys Swarm ignores, and how names are generated.

Creating services one docker service create at a time works for experiments, but real applications have many services, networks, volumes and secrets that must be created together and kept in version control. A stack is a group of such objects described in one YAML file and deployed with a single command. The file format is the Compose Specification, the same one used by docker compose, plus a deploy: section that only Swarm reads.

This lesson covers the shape of a stack file. The following lessons cover the deploy key and the stack commands. Swarm itself cannot run on this site, so file snippets are read-only; runnable blocks are stand-ins that check and transform stack data.

A minimal stack file

YAML
# stack.yml
services:
  web:
    image: nginx:1.27
    ports:
      - "80:80"
    networks: [frontend]
    configs:
      - source: nginx_conf
        target: /etc/nginx/nginx.conf
    deploy:
      replicas: 3

  api:
    image: myorg/api:1.4
    networks: [frontend, backend]
    secrets: [db_password]
    environment:
      DB_HOST: db
      DB_PASSWORD_FILE: /run/secrets/db_password

  db:
    image: postgres:17
    networks: [backend]
    volumes:
      - dbdata:/var/lib/postgresql/data
    secrets: [db_password]
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password

networks:
  frontend:
  backend:

volumes:
  dbdata:

configs:
  nginx_conf:
    file: ./nginx.conf

secrets:
  db_password:
    external: true

Deploy it with:

Terminal
docker stack deploy -c stack.yml shop

The last word, shop, is the stack name. Everything the file creates is prefixed with it, so the same file can be deployed twice under different names.

The top-level sections

  • services: each entry becomes a Swarm service named <stack>_<service>, for example shop_web.
  • networks: stack networks are created as overlay networks named <stack>_<network> (see the networking chapter). If you declare none, Swarm creates a stack-wide default overlay network that every service joins.
  • volumes: named volumes, created on whichever node runs the task. A volume is local to a node unless you use a volume driver that shares storage.
  • configs and secrets: either file: (Docker creates the object from a local file at deploy time) or external: true (the object must already exist, created with docker secret create). Use external for anything sensitive, so the value never sits in a file next to the stack.

DNS inside the stack uses the service name: the API reaches the database at host db, not shop_db, because both are on the backend network and Swarm's DNS resolves the short alias.

Keys that Swarm ignores

docker stack deploy is strict about what it supports. Notable differences from plain docker compose:

Key In a stack deploy
build: Ignored. Stacks deploy pre-built images; build and push first.
container_name: Not supported, because Swarm names tasks itself.
depends_on: Ignored. Start order is not enforced; services must retry until dependencies answer.
restart: Ignored. Use deploy.restart_policy.

The docker stack config command (available in current Docker releases) renders the merged file so you can see what will be deployed. For multiple files, pass several -c options and later files override earlier ones, which is the usual way to keep a base file and per-environment overrides.

flowchart LR
  F["stack.yml"] --> D["docker stack deploy -c stack.yml shop"]
  D --> S["services: shop_web, shop_api, shop_db"]
  D --> N["networks: shop_frontend, shop_backend"]
  D --> V["volumes: shop_dbdata"]

One file, one command, many named objects.

Naming and idempotence

Running docker stack deploy again with a changed file updates the existing stack: changed services roll, new services are created, and removed services are left alone unless you add --prune. The command is therefore both "install" and "upgrade". Deploying the same file twice changes nothing.

Terminal
docker stack deploy -c stack.yml shop --prune
docker stack services shop
docker stack ps shop
docker stack rm shop

docker stack rm removes services and networks but not volumes, so your data survives unless you remove the volumes yourself.

Stand-in: the stack name prefix

Python Stand-in: what names will a stack create?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: lint a stack file for ignored keys

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Common mistakes

  • Using build: and wondering why nothing builds.
  • Expecting depends_on to wait for the database. Make the app retry its connection instead.
  • Publishing the same port from two services in one stack.
  • Putting secret values in environment: instead of using secrets.
  • Forgetting that removing a service from the file does not remove it from the swarm without --prune.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the full name of the service web when the stack is deployed as shop?

    Swarm prefixes every object with the stack name and an underscore.
  2. 2. What happens to the build: key during docker stack deploy?

    Stacks deploy built images. Build and push in CI first.
  3. 3. How do you tell a stack file to use a secret that was created with docker secret create?

    external: true says the object already exists in the swarm.
  4. 4. Does docker stack rm delete named volumes?

    Volumes outlive the stack so data is not lost by accident.

Summary

  • A stack file is a Compose file deployed with docker stack deploy -c file name; all objects are prefixed with the stack name.
  • Secrets and configs can be file: based or external; use external for sensitive data.
  • build, container_name, depends_on and restart do not behave as in plain Compose.
  • Re-running deploy updates the stack; --prune removes services no longer in the file.

Next: The deploy Key: Replicas, Placement and Policies