Deploy and Safely Update a Docker Swarm Stack

You will deploy a small Compose file as a Docker Swarm stack, check whether its services have converged, and update or remove that stack deliberately. Allow about 15 minutes for a prepared Swarm and registry. The commands below use Docker CE CLI 29.8.1, installed from docker-ce-cli on this machine.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Check that this host is a Swarm manager
2. Prepare a Swarm-compatible Compose file
3. Deploy the named stack
4. Verify service convergence
5. Update the existing stack
6. Handle private images and credentials
7. Remove the test stack and recover safely

Scope: docker stack deploy is a Swarm manager command. It does not deploy to ordinary Docker Compose, and it does not build images. The examples change Docker state, so use a test stack name first if you are learning.

1. Check that this host is a Swarm manager

Run this as your normal user if your Docker socket is already accessible. The command only reads status:

$ docker info --format '{{.ServerVersion}} {{.Swarm.LocalNodeState}}'
29.8.1 active

You need an active Swarm and a manager node. On a new, disposable single-node host, an administrator can initialise one with sudo docker swarm init. That creates cluster state and may advertise this host to future workers, so do not run it on a production machine without an agreed Swarm design. A worker cannot run stack management commands.

Checkpoint: if the output says inactive, stop here and decide whether this host should join an existing Swarm or whether a test Swarm is appropriate. Do not work around the error by switching to docker compose up; that is a different deployment model.

2. Prepare a Swarm-compatible Compose file

Create a file named stack.yml in a working directory. This example uses a public image, publishes port 8080, and declares one replicated service:

services:
  web:
    image: nginx:1.27-alpine
    ports:
      - "8080:80"
    deploy:
      replicas: 1
      restart_policy:
        condition: on-failure

The stack command accepts Compose file version 3 and later in Docker's documented legacy stack format. Do not assume that every current Compose Specification feature is understood by Swarm. Fields that belong to local Compose, such as build, can be ignored or rejected rather than producing the service you intended.

For more than one Swarm node, every node must be able to pull the image. Use an image tag that your release process controls, or an immutable digest, rather than silently moving a floating tag between deployments.

3. Deploy the named stack

Choose a stack name that identifies the environment. The name becomes part of the names of the services, networks and volumes created by Docker:

$ docker stack deploy --compose-file stack.yml demo
Creating network demo_default
Creating service demo_web

The short option is -c, so docker stack deploy -c stack.yml demo is equivalent. You can pass more than one Compose file; later files supply overrides:

$ docker stack deploy -c stack.yml -c stack.production.yml demo

Docker exits immediately by default because --detach defaults to true in this installed release. A successful command means the desired services were submitted to Swarm, not that their tasks are already running. Use --detach=false when you want the command to wait for convergence, but still inspect the service afterwards.

4. Verify service convergence

Ask Swarm for the services in this stack:

$ docker stack services demo
ID             NAME       MODE         REPLICAS   IMAGE
...            demo_web   replicated   1/1         nginx:1.27-alpine

Wait for the REPLICAS value to show 1/1. With several replicas, it should show the requested count on both sides of the slash. If it remains at 0/1, inspect the task error rather than repeatedly redeploying:

$ docker service ps demo_web --no-trunc
$ docker service inspect demo_web --pretty

Common causes include an image that workers cannot pull, a published port already in use, an unsatisfied placement constraint, or a task that exits immediately. Check the service logs with docker service logs demo_web when the image and service support useful logging. Finally, test the published endpoint from a node that can reach the Swarm routing mesh:

$ curl --fail http://127.0.0.1:8080
<!DOCTYPE html>...

5. Update the existing stack

Edit the Compose file, then run the same deployment command with the same stack name:

$ docker stack deploy -c stack.yml demo
Updating service demo_web

Swarm compares the desired service definition with the existing one and applies the changes. Check docker stack services demo again, then inspect task history if a replacement does not become ready. Keep the previous image tag and configuration available until the new tasks have passed their health and application checks.

To remove services that no longer appear in the Compose files, add --prune to an intentional update:

$ docker stack deploy --prune -c stack.yml demo

Warning

Pruning removes stack services absent from the submitted configuration. Review the file and the change first. It is not a harmless synchronisation flag, and it will not preserve a service merely because another operator created it under the same stack.

6. Handle private images and credentials

If workers must pull from a private registry, log in with the Docker client used for deployment and consider --with-registry-auth:

$ docker login registry.example.invalid
$ docker stack deploy --with-registry-auth -c stack.yml demo

This sends registry authentication details to Swarm agents so they can pull the image. Treat the deployment as security-sensitive: restrict manager access, avoid putting passwords in shell history, and do not paste tokens into a Compose file. The flag is not needed for public images.

--resolve-image defaults to always. It asks the registry to resolve an image digest and supported platforms. Use changed or never only when your image distribution and repeatability requirements justify the change. If a registry is unavailable, a deployment that relies on fresh digest resolution can fail even when a worker has an older local copy.

7. Remove the test stack and recover safely

Destructive action

docker stack rm removes the stack's services, networks and other stack-managed resources. Confirm the name before running it:

$ docker stack ls
$ docker stack rm demo
Removing service demo_web
Removing network demo_default

There is no undo command. Redeploy from the Compose files to recreate the declared resources, but persistent data needs its own backup and recovery plan. Keep volumes and external resources out of a test experiment unless you have checked their lifecycle.

If you initialised a single-node test Swarm and no longer need it, leave it only after removing test workloads:

$ sudo docker swarm leave --force

That changes the host's cluster membership and is not a routine cleanup step for a production node.

Done means

The command ran on an active Swarm manager with the intended Docker CLI version.
The Compose file used fields supported by the stack deployment format and referenced pullable images.
docker stack services demo showed the requested replica count, and the endpoint was tested.
Updates used the existing stack name; --prune was used only after reviewing removals.
Registry credentials were handled as sensitive data, and the stack files and data needed for recovery remain available.