Push a Compose File to Swarm with stack deploy

The moment a Compose file must run across more than one machine, docker stack deploy is what turns it into live Swarm services. This walkthrough deploys a small file, checks convergence, then updates and removes the stack deliberately. Allow about 15 minutes for a prepared Swarm and registry.

docker stack deploy is a Swarm manager command. It does not deploy to ordinary Docker Compose, and it does not build images. The commands below use Docker CE CLI 29.8.1, installed from docker-ce-cli on this machine, and the examples change Docker state, so use a test stack name first if you are still learning the command.

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.

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

• Stick to the supported format. The stack command accepts Compose file version 3 and later in Docker's documented legacy stack format, not every current Compose Specification feature.
• Watch for ignored fields. Fields that belong to local Compose, such as build, can be ignored or rejected rather than producing the service you intended.
• Pin the image. Every node must be able to pull it. Use a tag 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; it becomes part of the names of the services, networks and volumes Docker creates:

$ 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 REPLICAS to show 1/1; with several replicas, both sides of the slash should match. If it stays 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 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 pass 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

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, keep passwords out of shell history, and never paste tokens into a Compose file. The flag is not needed for public images.

--resolve-image defaults to always, asking 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 relying on fresh digest resolution can fail even when a worker already has an older local copy.

7. Remove the test stack and recover safely

$ 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.