Skip to content

Lesson 26 ยท Stacks and Deployment

Stack Commands, Environments and Overrides

Learn every docker stack command, how variable substitution and multiple -c files give you dev, staging and production variants, and common deploy flags.

You now know what goes into a stack file. This lesson is about operating it: the docker stack commands, how to feed per-environment values into one file, and how to layer override files so that staging and production differ only where they must.

The commands are read-only text on this site (no Swarm here). The runnable blocks are Python stand-ins that reproduce variable substitution and file merging so you can see the rules at work.

The docker stack commands

Terminal
docker stack deploy -c stack.yml shop      # create or update
docker stack ls                            # all stacks
docker stack services shop                 # services with replica counts
docker stack ps shop                       # every task, including old ones
docker stack ps shop --no-trunc            # full error messages
docker stack rm shop                       # remove services and networks
docker stack config -c stack.yml           # print the merged file

docker stack services is the quick health view: a column such as 3/4 means three of four requested replicas are running. docker stack ps shows the history; failed tasks keep their error text, which explains why a container died or why a task never scheduled.

Useful flags for deploy:

Flag Effect
-c, --compose-file The stack file. Repeat it to merge several files.
--with-registry-auth Send your registry login to the nodes so they can pull private images.
--prune Remove services that are no longer in the file.
--resolve-image always|changed|never Control whether the registry is queried for the image digest.
-d, --detach=false Wait for the services to converge instead of returning at once.

In recent Docker releases deploy waits and reports progress by default; older releases returned immediately, so scripts often pass --detach=false explicitly to be safe.

Variable substitution

Stack files support shell-style variables, which the client replaces before sending anything to the swarm:

YAML
services:
  web:
    image: myorg/web:${TAG:-latest}
    deploy:
      replicas: ${WEB_REPLICAS:-2}
    ports:
      - "${HTTP_PORT:-8080}:80"

${VAR} is replaced with the environment variable; ${VAR:-default} uses the default if the variable is unset or empty; ${VAR:?message} aborts with an error if it is missing, which is a good guard for something like an image tag. Deploy with:

Terminal
TAG=1.5.2 WEB_REPLICAS=6 docker stack deploy -c stack.yml shop

An important detail: the classic docker stack deploy does not read a .env file automatically. Either export the variables, use env $(cat .env) docker stack deploy ... on a shell you trust, or render the file first with docker compose --env-file prod.env -f stack.yml config | docker stack deploy -c - shop. Rendering first also makes the exact deployed YAML easy to archive.

Override files

Keep a base file with everything shared, and small files that change only what differs:

YAML
# stack.prod.yml
services:
  web:
    deploy:
      replicas: 6
      resources:
        limits:
          memory: 256M
Terminal
docker stack deploy -c stack.yml -c stack.prod.yml shop

Files are merged from left to right. Mappings (such as deploy) are merged key by key; scalar values from the later file win; lists such as ports or environment entries are combined or replaced depending on the key, so check the result with docker stack config -c stack.yml -c stack.prod.yml before you ship it.

flowchart LR
  B["stack.yml<br/>(shared)"] --> M["merge"]
  O["stack.prod.yml<br/>(overrides)"] --> M
  V["TAG, REPLICAS<br/>(environment)"] --> M
  M --> D["docker stack deploy"]

Base file, override file and environment combine on the client before deployment.

Image tags and digests

Deploy immutable tags (1.5.2) or digests (@sha256:...), never latest. If the tag moves, Swarm may run different images on different nodes, because each node pulls independently. By default the manager resolves the tag to a digest when the service is created or updated, so all tasks of one version use the same bytes.

Stand-in: substitution rules

Python Stand-in: ${VAR:-default} and ${VAR:?error}

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: merge a base file with an override

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

  • Assuming .env is loaded automatically by docker stack deploy.
  • Deploying latest and getting different images on different nodes.
  • Forgetting --with-registry-auth for private registries, so workers fail with "pull access denied".
  • Removing a service from the file but not passing --prune.
  • Never viewing the merged result before deploying an override.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command shows how many of the requested replicas are running for each service in a stack?

    docker stack services lists each service with a replicas column such as 3/4.
  2. 2. In ${TAG:-latest}, what happens when TAG is unset?

    :- supplies a default when the variable is unset or empty.
  3. 3. Why pass --with-registry-auth?

    The credentials are forwarded to the nodes that pull the image.
  4. 4. How are multiple -c files combined?

    Later files override or extend earlier ones; verify with docker stack config.

Summary

  • docker stack deploy/ls/services/ps/rm/config cover the whole lifecycle; deploy is both install and update.
  • Variables are substituted by the client; .env is not read automatically by classic docker stack deploy.
  • Layer a base file with small per-environment overrides and inspect the merge before deploying.
  • Pin image tags or digests and use --with-registry-auth for private registries.

Next: Private Registries and Image Delivery