Docker Swarm Overview

Docker Compose runs an app on one server. When a company needed several servers before Kubernetes became the usual answer, many chose Docker Swarm mode, the clustering feature built into Docker Engine itself. Swarm is still part of Docker Engine 29, still maintained, and still running in production at many companies, especially smaller ones that wanted something simpler than Kubernetes.

You may join a team in Gurugram or Pune whose deployment scripts say docker stack deploy. This lesson gives you enough Swarm to understand and operate such a setup: the main ideas, the everyday commands and how it compares with Compose and Kubernetes. For new clusters, most teams today choose Kubernetes, which has its own Kubernetes course.

The main ideas

Managers agree on the cluster state using the Raft algorithm, which needs a majority of managers to be available. That is why production swarms use an odd number of managers: three managers survive the loss of one, five survive the loss of two.

Create a swarm

On the first server, whose private address is 10.0.0.11:

docker swarm init --advertise-addr 10.0.0.11

Swarm initialized: current node (dxn1zf6l61qsb1josjja83ngz) is now a manager.

To add a worker to this swarm, run the following command:

    docker swarm join --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c 10.0.0.11:2377

To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.

This output follows the format in Docker's Swarm tutorial; your IDs and token differ. Run the printed docker swarm join command on each worker. The join token is a secret: anyone who has it can add a machine to your cluster. The nodes must reach each other on TCP port 2377 (cluster management), TCP and UDP 7946 (node communication) and UDP 4789 (overlay network traffic), on a private network rather than the internet.

docker node ls --format '{{.Hostname}}  {{.Status}}  {{.Availability}}  {{.ManagerStatus}}'

swarm-1  Ready  Active  Leader
swarm-2  Ready  Active
swarm-3  Ready  Active

swarm-1 is the manager and the current leader; an empty manager status means a worker.

Services, scaling and rolling updates

On a manager, you create services instead of running containers:

docker service create --detach --name menu --replicas 3 -p 8080:80 nginx:1.29-alpine
docker service ls

k3l9x2m4p7q1v8w5z0a6b2c4d
ID             NAME      MODE         REPLICAS   IMAGE               PORTS
k3l9x2m4p7q1   menu      replicated   3/3        nginx:1.29-alpine   *:8080->80/tcp

Swarm spreads the three tasks over the nodes. If a node dies, the manager starts replacement tasks on the others. The published port uses the routing mesh: port 8080 is open on every node, and a request to any node is forwarded to a healthy task, even one on another server.

Scaling and updating are single commands:

docker service scale menu=5
docker service update --image nginx:1.30-alpine \
  --update-parallelism 1 --update-delay 10s menu
docker service ps menu
docker service rollback menu

docker service update replaces tasks one at a time (--update-parallelism 1) with a 10-second pause between them, so the service stays available during the update. docker service ps shows each task with its node and state. If the new version misbehaves, docker service rollback returns to the previous settings. The image tags here are examples; use versions that exist.

Stacks: Compose files for a cluster

A stack deploys several services from a Compose-style file:

services:
  api:
    image: ghcr.io/kabir-mehta/results-api:2.4.0
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 10s
      resources:
        limits:
          memory: 512M
    secrets: [db_password]
    networks: [backend]

  db:
    image: mysql:8.4
    deploy:
      placement:
        constraints: ["node.labels.disk == ssd"]
    networks: [backend]

secrets:
  db_password:
    external: true

networks:
  backend:
    driver: overlay

printf '%s' 'Change-Me-Strong-Password' | docker secret create db_password -
docker stack deploy -c stack.yaml results
docker stack services results

Points that surprise Compose users:

• docker stack deploy uses the older Compose file format version 3, not the full current Compose Specification, so some newer keys are not supported.
• build: is ignored (Ignoring unsupported options: build). Every node pulls images from a registry, so images must be built and pushed first.
• deploy: settings (replicas, update order, placement, resources) are where most of the cluster behaviour lives.
• Swarm secrets are stored encrypted by the managers and mounted only into tasks that need them, at /run/secrets/NAME. docker secret create NAME - reads the value from standard input, so it does not appear as a command argument.
• A placement constraint pins the database to nodes labelled for it, because its volume exists only on that node's disk. Stateful services are where Swarm (and every orchestrator) needs the most care.

Swarm, Compose or Kubernetes?

If you inherit a working swarm, it is reasonable to keep running it and learn it well. If you are designing a new multi-server platform, compare with Kubernetes first; the ideas you learned here (desired state, replicas, rolling updates, secrets) carry straight over.

Common mistakes

• Two managers. Losing one leaves no majority, and the cluster cannot change state. Use one, three or five managers.
• Using build: in a stack file. It is ignored; push images to a registry first.
• Leaking the join token. Rotate it with docker swarm join-token --rotate worker.
• Opening Swarm ports to the internet. Keep 2377, 7946 and 4789 on a private network.
• Running a database with replicas and local volumes. Each replica gets its own empty volume; pin stateful services with constraints.

Key points

• Swarm mode is the clustering feature built into Docker Engine; it is maintained and common in existing setups.
• Managers (use an odd number) keep the state with Raft; workers run tasks; services describe the desired state.
• docker service create, scale, update and rollback give replicas, self-healing and rolling updates; the routing mesh publishes ports on every node.
• docker stack deploy -c file.yaml NAME deploys a Compose version 3 style file; build is ignored and deploy: holds cluster settings.
• For new multi-server platforms, most teams choose Kubernetes; the concepts carry over.

docker node ls
docker stack services canteen
docker service scale canteen_api=4
docker service update --image ghcr.io/aarav-shah/canteen-api:1.8.0 \
  --update-parallelism 1 --update-delay 15s canteen_api
docker service rollback canteen_api