Skip to content
Blog

Docker Swarm in Depth: Init, Services, and Stacks

A hands-on tour of swarm mode: `docker swarm init`, services vs containers, replicated vs global tasks, overlay networks, and stacks via `docker stack deploy`.

Published on • November 14, 2026

AI Assistant

docker run gives you one container on one host. Swarm mode — the orchestration layer built into Docker Engine itself — turns the same binary into a cluster scheduler: replicas, rolling updates, overlay networks, and a load balancer, with no extra control plane to install. This is a hands-on walkthrough from empty nodes to a stack you can roll back.

Swarm mode ships with the Engine

There is nothing to download. Swarm mode runs on top of swarmkit, the same open-source toolkit Docker uses internally, and it reuses the Docker daemon you already have. The mental model has four pieces:

  • Manager nodes hold cluster state and make scheduling decisions. State is replicated across managers with Raft — you want an odd number (1, 3, 5) so leader election survives a node loss.
  • Worker nodes run tasks. They don’t store cluster state; if a worker dies, a manager notices and reconciles.
  • Services are the unit of desired state: “I want 3 replicas of nginx:1.27.”
  • Tasks are the atomic scheduling unit. Once a task is assigned to a node it cannot migrate — it either runs there or fails, and the manager starts a replacement elsewhere.

That last rule is worth internalizing: Swarm doesn’t move containers to rebalance, it kills and recreates them. State lives in volumes or outside the cluster.

Init and join: a three-node cluster

On the first machine, become a manager:

docker swarm init --advertise-addr 10.0.0.11
docker swarm join-token worker   # prints the join command

--advertise-addr matters on multi-homed hosts — it’s the address other nodes use to reach this one. On the workers, run the printed command verbatim:

docker swarm join --token SWMTKN-1-xxxx 10.0.0.11:2377

Port 2377 is cluster management, 7946 is node-to-node discovery, and 4789 is the VXLAN overlay data path — open those between nodes or the cluster will half-form in confusing ways. Confirm from a manager:

docker node ls
docker info --format '{{.Swarm.ControlAvailable}}'

ControlAvailable returning true confirms this node can run service commands. A worker will say false — that’s expected, not an error.

Replicated vs global services

Create your first service:

docker service create --name web --replicas 3 \
  --publish published=8080,target=80 \
  nginx:1.27
docker service ps web
docker service ls

The --publish flag is where ingress load balancing appears: you publish a port on every node, and Swarm’s routing mesh forwards incoming traffic to a running task wherever it lives. Leave the published port unspecified and Swarm auto-assigns one from 30000–32767 — handy for demos, surprising in production.

Two modes:

  • Replicated (--replicas N) — spread N tasks across nodes by the scheduler’s placement rules. This is the default and what 90% of services want.
  • Global (--mode global) — exactly one task per eligible node. Use this for log shippers, node exporters, anything that must exist on every machine.

Scaling is one command, and it’s a desired-state change, not a shell hack:

docker service scale web=6
docker service update --image nginx:1.27.2 web

docker service update also handles rolling updates: by default one task at a time with a 0s delay between them; --update-delay 10s --update-parallelism 2 gives you a saner rollout, and --update-order start-first keeps the old task alive until the new one is up.

Internal DNS and overlay networks

Swarm gives every service an internal DNS name. On a user-defined overlay network, tasks of service api resolve db to a virtual IP, and traffic round-robins across healthy tasks — no external load balancer needed for east-west traffic:

docker network create --driver overlay backend
docker service create --name api --network backend my/api:1.4
docker service create --name db  --network backend postgres:16

Cross-node container communication happens over VXLAN on port 4789. Encryption is opt-in (--opt encrypted) and costs throughput — measure before enabling it everywhere.

Stacks: Compose files on the cluster

For anything more than one service, stop typing docker service create. A stack is a Compose file deployed to the cluster:

# docker-compose.yml
version: "3.8"
services:
  api:
    image: my/api:1.4
    ports:
      - "8080:8080"
    deploy:
      replicas: 3
      update_config:
        parallelism: 2
        delay: 10s
      rollback_config:
        parallelism: 1
    networks:
      - backend
  db:
    image: postgres:16
    networks: [backend]
networks:
  backend:
    driver: overlay

Deploy it:

docker stack deploy -c docker-compose.yml shop
docker stack services shop
docker stack rm shop

Note the deploy: key — Swarm ignores it in plain docker compose up and honors it under docker stack deploy. That’s the main Compose/Swarm compatibility wrinkle: replicas, update policy, rollback policy, placement constraints, and resource limits all live there.

Rollback and the reconciliation loop

Say the new image is broken. Roll back to the previous spec:

docker service update --rollback web
docker service ps web --no-trunc

--no-trunc shows you the full task history, including the previous failures — Swarm keeps old task records precisely so you can see what happened during a bad rollout.

Underneath, everything is a desired-state reconciliation loop: docker service ls shows the spec, docker service ps shows reality, and a manager constantly narrows the gap. Worker dies? Its tasks are marked rejected and new ones are scheduled elsewhere. Node drained for maintenance? docker node update --availability drain ip-10-0-0-12 moves work off it gracefully — tasks are stopped and rescheduled, not live-migrated.

The operational limits are real and worth stating: no CRDs or operators, no HorizontalPodAutoscaler (you scale with docker service scale or external tooling hitting the API), no Helm ecosystem, and a much smaller hiring pool. But for a team that wants replication, TLS between nodes by default, rolling updates, and rollback without operating a control plane, swarm mode remains the shortest path from docker run to a production cluster.

Further reading