Docker Swarm Cheat Sheet

1Init & joinform the swarm

docker swarm init --advertise-addr 10.0.0.1★
Run on the first node — it becomes a manager. --advertise-addr is the IP other nodes reach it on. Prints the worker join command.
docker swarm join --token SWMTKN-... 10.0.0.1:2377★
Run on each other host to join as a worker. Port 2377 = cluster management (TCP).
docker swarm join-token manager · worker
Print the token to add more managers or workers. Rotate a leaked token with join-token --rotate (card 3).
docker swarm leave --force # --force on a manager
Remove a node from the swarm. docker node rm <id> from a manager to evict a downed node.

2Managing nodesmanagers & workers

docker node ls★
List nodes with role (manager/worker), status, and availability. Run only on a manager.
docker node promote <node> · docker node demote <node>
Change a node between worker and manager. Keep an odd number of managers (3 or 5) for Raft quorum.
docker node update --availability drain <node>★
Drain moves tasks off a node (for maintenance). active to return it; pause to stop new tasks only.
docker node update --label-add zone=eu <node>
Add labels used later by placement constraints (card 13).
# losing manager quorum = the cluster can't schedulegotcha
Managers use Raft; if more than half are down you lose quorum. Spread 3/5 managers across failure domains; keep workers plentiful. Recover from backup or swarm init --force-new-cluster.

3Cluster securityautolock · CA · tokens

docker swarm init --autolock · docker swarm update --autolock=true★harden
Autolock encrypts the Raft logs (which hold secrets/configs) at rest; after a daemon restart the swarm stays locked until you supply the unlock key. Prints the key on enable.
docker swarm unlock # paste key after a restart docker swarm unlock-key --rotate # rotate the unlock key★
unlock re-enables an autolocked manager; unlock-key prints (or rotates) the current key. ⚠️ Store the key in a password manager — lose it and a fully-restarted autolocked swarm can't recover.
docker swarm join-token --rotate worker
Invalidate a leaked join token and issue a new one (existing members stay joined). Do this if a token ever leaks.
docker swarm ca --rotate · docker swarm update --cert-expiry 720h
Rotate the cluster CA and re-issue every node's TLS cert (mutual TLS is automatic). Node certs auto-renew (default 90 days); tune with --cert-expiry.

4Servicesthe unit of work

docker service create --name web --replicas 3 -p 80:80 nginx:alpine★
A service = the desired state of a containerized app across the cluster. Swarm schedules --replicas tasks and keeps them running.
docker service create --mode global --name agent monitoring:latest
global mode runs exactly one long-running task on every node (log/metrics agents). Default is replicated.
docker service ls · docker service ps web★
ls shows services & replica counts; ps <svc> shows each task, its node, and state (running/failed/rejected).
docker service logs -f web · docker service rm web
Aggregate logs across replicas; remove the service.

5Service jobsrun to completion

docker service create --mode replicated-job \ --replicas 10 --max-concurrent 2 --name migrate migrate:latest★jobs
A replicated job runs --replicas tasks to completion (not forever), --max-concurrent at a time (default = replicas). For batch work: DB migrations, imports, one-off scripts.
docker service create --mode global-job --name cleanup cleanup:latest
A global job runs exactly one task on every current node, once — e.g. a node-local cleanup/backup pass. No --replicas.
docker service ps migrate # tasks show state "Complete", not "Running"
Jobs differ from services: a service restarts finished tasks; a job's tasks finish and stay Complete. Re-run by service update --force.
# jobs need Engine 20.10+; older engines reject the *-job modesversion
Service jobs landed in Docker Engine 20.10. On older daemons use a one-shot replicated service with --restart-condition none instead.

6Scale & updatechange desired state

docker service scale web=5★
Change replica count (or service update --replicas 5). Swarm converges to the new desired state.
docker service update --image nginx:1.27 --update-order start-first web★
Roll out a new image. --update-order start-first starts the new task before stopping the old — true zero-downtime when you have spare capacity (default is stop-first).
docker service update --env-add KEY=val --publish-add 443:443 web
Add/remove env, ports, mounts, labels, limits with --*-add/--*-rm flags. --force redistributes tasks with no spec change.
docker service rollback web★
Revert to the previous spec if an update goes wrong (rollout controls in card 14).

7Service templatingper-task values

docker service create --hostname "{{.Node.Hostname}}" --name app app:latest★templates
Swarm expands Go-template placeholders per task at schedule time — give each replica a hostname derived from its node. Works in --hostname, --env, and --mount.
--env NODE="{{.Node.ID}}" --mount ...,target=/data/"{{.Task.Slot}}"
Give each replica a unique path/identity — useful for per-replica data dirs or node-aware config.
# placeholders: .Service.ID/.Name/.Labels · .Node.ID/.Hostname · .Task.ID/.Name/.Slot
The full set of template variables. .Task.Slot is the stable 1..N replica index — handy for sharding.

8Overlay networksmulti-host

docker network create -d overlay backend★
Overlay is the network type for cross-node service traffic. Attach services and they resolve each other by service name via built-in DNS.
docker service create --network backend --name api api:latest★
A service on backend reaches web at http://web — Swarm gives each service a virtual IP that load-balances to its tasks.
docker network create -d overlay --opt encrypted secure docker network create -d overlay --attachable shared
--opt encrypted turns on IPsec encryption of the data plane between nodes; --attachable lets standalone containers join the overlay (handy for debugging).
# open 7946 (tcp/udp) + 4789 (udp) between nodes; 2377 (tcp) to managersfirewall
Overlay needs 7946 (control) and 4789 (VXLAN data) open between hosts. The built-in ingress overlay carries routing-mesh traffic.

9Routing mesh & portspublish

docker service create -p 8080:80 web★
Routing mesh: the published port 8080 is reachable on every node's IP — requests are load-balanced to the service's tasks wherever they run.
docker service create --publish mode=host,target=80,published=8080 web
mode=host bypasses the mesh — the port maps only on nodes running a task (for an external LB / high-perf paths).
# front the mesh with an external LB / Traefik for TLS & routing
Put nginx/Traefik/HAProxy in front for TLS termination, host/path routing, and sticky sessions.

10StacksCompose in prod

docker stack deploy -c docker-compose.yml myapp★
Deploy a whole multi-service app from a Compose file to the swarm. A stack groups services, networks & volumes under one name.
# compose file uses the `deploy:` key (swarm-only) deploy: {replicas: 3, restart_policy: {condition: on-failure}, update_config: {parallelism: 1, delay: 10s, order: start-first}}★
The deploy: block sets replicas, placement, resources, rollout & restart policy — it's ignored by docker compose up, used only by stack deploy.
docker stack ls · stack services myapp · stack ps myapp
List stacks, their services, and tasks. docker stack rm myapp to tear down.
# `build:` is not supported by stack deploy — push a pre-built imagegotcha
Stacks can't build images; build & push to a registry first, reference the tag in the Compose file. Add --with-registry-auth to ship your registry creds to the nodes.

11Secrets & configsinject data safely

echo "s3cr3t" | docker secret create db_pw -★
Secrets are encrypted at rest & in transit, and mounted in-memory at /run/secrets/<name> — never in env vars or the image.
docker service create --secret db_pw --name api api:latest★
Grant a service access; the app reads the file at /run/secrets/db_pw. Target path/uid/gid/mode are tunable via the long --secret source=...,target=... form.
docker config create nginx_conf ./nginx.conf
Configs are the non-secret twin — ship config files to services (mounted at a path you choose) without baking them into images.
# secrets/configs are immutable — rotate by creating a new onegotcha
You can't edit a secret in place. Create db_pw_v2, then service update --secret-rm db_pw --secret-add db_pw_v2.

12Cluster volumes (CSI)portable storage

docker volume create --driver <csi-plugin> --type mount \ --sharing all --scope multi --required-bytes 1G --limit-bytes 10G data★CSI
Cluster volumes use the CSI standard so a service's storage follows it to whatever node it lands on (cloud disks, NFS, Ceph). --scope multi + --sharing all allow multi-node access; --type mount (filesystem) or block.
docker service create --mount type=cluster,src=data,dst=/srv/www --name web nginx★
Consume it with type=cluster. Swarm places tasks where the volume's topology allows and (re)attaches the volume on failover — unlike a per-node local volume.
# the CSI plugin must be installed on ALL manager nodes (+ workers that use it)gotcha
Swarm ships the CSI framework (since Engine 23) but no built-in provider — install a CSI plugin yourself. Missing it on a manager breaks the driver after a leadership change.

13Placement & resourceswhere tasks run

docker service create --constraint 'node.role==worker' web★
Restrict scheduling by node role, hostname, or labels (node.labels.zone==eu). Keep app workloads off managers.
docker service create --placement-pref 'spread=node.labels.zone' \ --replicas-max-per-node 2 web
Spread replicas evenly across a label (zones/racks); --replicas-max-per-node caps how many tasks land on any one node.
docker service create --reserve-memory 256M --limit-cpu 0.5 web
Reserve (for scheduling) and limit (hard cap) resources per task. Unschedulable reservations leave tasks pending.
docker service create --mount type=volume,source=data,target=/data web
Local/driver volumes are per-node; for storage that moves with the task use a cluster volume (card 12).

14Rolling updates & healthsafe deploys

docker service update --update-parallelism 1 --update-delay 10s web★
Update N tasks at a time with a pause between batches — the core of zero-downtime deploys. Pair with --update-order start-first (card 6).
--update-failure-action rollback --update-monitor 30s★
Auto-rollback if updated tasks fail within the monitor window — combine with a healthcheck.
--rollback-parallelism 2 --rollback-monitor 20s --rollback-order start-first
Rollbacks have their own controls, distinct from updates: --rollback-parallelism/-delay/-monitor/-failure-action/-order. Tune how fast a bad deploy unwinds.
docker service create --health-cmd 'curl -f localhost/health' \ --health-interval 5s --health-retries 3 --health-start-period 20s web★
Healthchecks gate rollouts & restarts — a task isn't "ready" until healthy, so bad versions don't take traffic. --health-start-period covers slow boots.

15Inspect & debugwhat's wrong

docker service ps --no-trunc web★
See why tasks failed — the error column (image pull, constraint unsatisfiable, OOM) is truncated by default.
docker service inspect --pretty web · docker events -f type=service
Full resolved spec (image, networks, mounts, env, update policy); docker events streams cluster activity live.
docker node inspect --pretty <node> · docker system df
Node capacity/labels/plugins; disk usage across the host.
# task stuck "pending"? no node satisfies constraints/resources/topologygotcha
A task that won't schedule usually means an unsatisfiable constraint, insufficient resources, a missing volume/secret, or (for CSI) no node in the volume's topology.

16Swarm vs Kuberneteschoosing

# Swarm: simple, batteries-included, same Docker CLI & Compose★
Best for small/medium clusters, homelabs, and teams that want orchestration without the Kubernetes learning curve — secrets, overlay networking, rolling updates all built in.
# Kubernetes: bigger ecosystem, autoscaling, operators, huge scale
Reach for K8s when you need horizontal pod autoscaling, a rich operator/Helm ecosystem, or very large multi-team clusters. Swarm has no built-in autoscaler.
# Portainer / Traefik / keel are common Swarm companions
Portainer (GUI), Traefik (ingress/TLS), and auto-update tools round out a Swarm stack.
docker compose up # single host vs docker stack deploy # swarm
Same Compose file, two runtimes: Compose for one host/dev, Swarm stacks for the cluster.

Docker Swarm cheat sheet

Outline

Cluster & services

Services & networking

Storage & ops

Cluster, Nodes & Security

Services & Networking

Stacks, Secrets & Storage

Ops & Ecosystem

Worth memorizing