🐝 Docker Swarm Overview

What Is Docker Swarm?

Docker Swarm (officially "swarm mode") is Docker's native clustering and orchestration feature. It groups a pool of Docker hosts into a single virtual host so you can run containers across all of them and treat the group as one. The best part: there's nothing new to install — swarm mode ships inside Docker Engine and uses the same docker command you already know.

The name fits. Picture a beehive: many worker bees each do a small job, a manager coordinates the hive, and together they behave like one organism. Swarm coordinates many containers across many machines the same way — you give one instruction and the swarm spreads the work.

The mental shift: containers to services

With plain Docker you think in containers — you start each one yourself. With Swarm you think in services. A service says "keep 3 copies of this image running somewhere in the cluster," and Swarm places them, watches them, and replaces any that fail. That's the same desired-state idea you met with Kubernetes, expressed in Docker's simpler vocabulary.

Managers & Workers

A swarm is made of nodes — each node is one Docker host. Nodes have two roles, mirroring the control-plane / worker split you saw in Kubernetes:

• Manager nodes run the control plane. They accept your commands, store the desired state, decide where tasks run, and keep reality matching your intent. One manager is elected the leader.
• Worker nodes just run the containers ("tasks") the managers assign to them and report back their status.

A manager can also run workloads, so a small swarm might be a few managers that double as workers.

How managers stay in sync: Raft

Multiple managers exist for fault tolerance, but they must agree on the cluster's state. Swarm uses the Raft consensus algorithm to replicate that state across managers and elect a leader. Raft needs a majority (a quorum) to make decisions, which is why you run an odd number of managers:

💡 Why odd numbers? A quorum is "more than half." With 4 managers you still only tolerate 1 failure — the same as 3 — but you've added cost and risk. Three or five is the sweet spot for most swarms.

Creating a Swarm

Turning a lone Docker host into a swarm manager is a single command. The output hands you a token that other machines use to join.

Initialize the first manager

# Run on the machine that will be your first manager
docker swarm init --advertise-addr 192.168.1.10

# Swarm prints a ready-to-paste join command, for example:
#   docker swarm join --token SWMTKN-1-49nj1cmql... 192.168.1.10:2377
# The 2377 port is the swarm management port.

Join more nodes

# On each worker machine, paste the join command from above
docker swarm join --token SWMTKN-1-49nj1cmql... 192.168.1.10:2377
#   "This node joined a swarm as a worker."

# Need the manager token instead? Ask an existing manager:
docker swarm join-token manager

Inspect and manage nodes

# List every node and its role and status (run on a manager)
docker node ls

# Promote a worker to manager, or demote a manager to worker
docker node promote worker-hostname
docker node demote  manager-hostname

# Drain a node before maintenance so tasks move off it
docker node update --availability drain worker-hostname

$ docker node ls
ID              HOSTNAME    STATUS   AVAILABILITY   MANAGER STATUS
xk9p2 *         node-1      Ready    Active         Leader
8mzq7           node-2      Ready    Active         Reachable
q4vlt           node-3      Ready    Active
# The * marks the node you are currently on.

Services & Tasks

A service is the unit you deploy in Swarm — the desired state for one containerized workload. Each running copy of a service is a task, and a task is just a container the scheduler placed on some node. If a task dies, Swarm starts a new one to keep the replica count you asked for.

Create and scale a service

# Create a replicated service: 3 copies of nginx, published on port 80
docker service create --name web --replicas 3 --publish 80:80 nginx:1.27

# See services and the individual tasks
docker service ls
docker service ps web        # which node each task runs on

# Scale by changing the desired replica count — Swarm does the rest
docker service scale web=5

There are two service modes. Replicated (the default) runs a fixed number of copies you choose. Global runs exactly one copy on every node — perfect for a monitoring or logging agent that must live everywhere:

# One task per node, automatically, even as nodes join or leave
docker service create --name node-agent --mode global monitoring-agent:latest

Rolling updates & rollback

Swarm ships new versions gradually so the service never fully goes down, and can undo a bad release:

# Update the image, two tasks at a time, pausing 10s between batches
docker service update \
  --image nginx:1.28 \
  --update-parallelism 2 \
  --update-delay 10s \
  web

# Something wrong? Roll back to the previous definition
docker service rollback web

Built-in load balancing: the routing mesh

When you publish a port, Swarm's routing mesh makes that port answer on every node, then forwards each request to a healthy task — even a task on a different node. So a client can hit any node's IP and still reach your service. That's service discovery and load balancing with zero extra setup.

Stacks & Compose

Real apps have several services — a web tier, an API, a database, a cache. A stack is a group of related services deployed together from a single Compose file. If you've used Docker Compose in development, deploying to a swarm feels almost identical: the same YAML, one deploy command.

# docker-compose.yml — a two-service stack
services:
  web:
    image: nginx:1.27
    ports:
      - "80:80"
    deploy:                 # the deploy key is what Swarm reads
      replicas: 3
      update_config:
        parallelism: 1
        delay: 10s
      restart_policy:
        condition: on-failure
    networks:
      - appnet

  api:
    image: ghcr.io/acme/api:2.1
    deploy:
      replicas: 2
      placement:
        constraints:
          - node.role == worker   # keep the API off manager nodes
    networks:
      - appnet

networks:
  appnet:
    driver: overlay           # overlay networks span multiple hosts

# Deploy the whole stack under the name "myapp"
docker stack deploy -c docker-compose.yml myapp

# Inspect what you deployed
docker stack ls              # all stacks
docker stack services myapp # services in this stack
docker stack ps myapp       # every task and where it runs

# Tear it all down
docker stack rm myapp

Swarm vs. Kubernetes

Both orchestrate containers across many hosts with self-healing, scaling, and rolling updates. The real difference is simplicity versus power. Swarm optimizes for "up and running in minutes with tools you know." Kubernetes optimizes for "handle almost anything at almost any scale," at the cost of a steeper climb.

Choose Swarm when…

• Your team already lives in Docker and wants minimal new tooling
• The app is small-to-medium and you value a fast, simple setup
• You need clustering for a side project, internal tool, or edge deployment

Choose Kubernetes when…

• You expect large scale or complex microservice topologies
• You want autoscaling and a rich ecosystem of tools and integrations
• You'll use a managed cloud service (EKS, GKE, AKS) and have ops capacity

💡 The honest state of things: Kubernetes has clearly won as the default industry standard, so most job postings ask for it. Swarm is still an excellent, underrated choice for simpler needs — and learning it makes the Kubernetes concepts click faster.

Practice & Quiz

docker swarm init
docker service create --name site --replicas 2 --publish 8080:80 nginx:1.27
docker service scale site=4
docker service ps site      # should list 4 running tasks

Best Practices & Pitfalls

✅ Do

• Run 3 or 5 manager nodes for production fault tolerance
• Define multi-service apps as stacks in a Compose file kept in version control
• Use overlay networks so services on different nodes can talk securely
• Configure update_config and restart_policy so rollouts and recovery are automatic
• Store passwords with Docker secrets, not plain environment variables

❌ Don't

• Don't run a single manager in production — one failure and you lose the control plane
• Don't use an even number of managers; it adds cost without added tolerance
• Don't expect Swarm to autoscale for you — scaling is a manual command
• Don't forget to open swarm ports (2377, 7946, 4789) between nodes, or joins and networking fail

Summary

📚 Additional Resources

• Docker — Swarm mode overview
• Docker — Getting started with swarm mode
• Docker — Deploy a stack to a swarm
• Docker — Manage secrets in swarm

🚀 What's Next?

You've now met both orchestrators. Whichever you pick, the day-to-day job is keeping containers healthy — watching resource use, setting restart policies, collecting logs, and running health checks. Next up: Container Management Patterns, the practices that apply across every platform.