Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 38 ยท 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