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.
docker swarm join-token manager · worker
Print the token to add more managers or workers. Rotate a leaked token with join-token --rotate.
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 9).
# 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.

3Servicesthe 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 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.

4Scale & 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 web★
Roll out a new image — Swarm updates tasks per the rolling-update policy (card 10).
docker service update --env-add KEY=val --publish-add 443:443 web
Add/remove env, ports, mounts, labels, limits with --*-add/--*-rm flags.
docker service rollback web★
Revert to the previous spec if an update goes wrong.

5Overlay networksmulti-host

docker network create -d overlay backend★
Overlay is the only 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 --attachable shared
--attachable lets standalone containers (not just services) join the overlay — handy for debugging.
# open ports 7946 (tcp/udp) + 4789 (udp) between nodesfirewall
Overlay needs 7946 (control) and 4789 (VXLAN data) open between hosts, plus 2377 to managers.

6Routing 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 a load balancer / 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.

7StacksCompose 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}}★
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.

8Secrets & 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.
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, service update --secret-rm db_pw --secret-add db_pw_v2.

9Placement & constraintswhere 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' web
Spread replicas evenly across a label (zones/racks) for resilience.
docker service create --reserve-memory 256M --limit-cpu 0.5 web
Reserve (for scheduling) and limit (hard cap) resources per task.
docker service create --mount type=volume,source=data,target=/data web
Attach volumes; for shared state across nodes use a networked/driver volume (NFS, cloud), since local volumes are per-node.

10Rolling 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.
--update-failure-action rollback --update-monitor 30s★
Auto-rollback if updated tasks fail within the monitor window — combine with a healthcheck.
docker service create --health-cmd 'curl -f localhost/health' \ --health-interval 5s --health-retries 3 web★
Healthchecks gate rollouts & restarts — a task isn't "ready" until healthy, so bad versions don't take traffic.
--restart-condition on-failure --restart-max-attempts 3
Restart policy for crashed tasks.

11Inspect & 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
Full resolved spec: image, networks, mounts, env, update policy.
docker node inspect --pretty <node> · docker system df
Node capacity/labels; disk usage across the host.
# task stuck "pending"? no node satisfies constraints/resourcesgotcha
A task that won't schedule usually means an unsatisfiable constraint, insufficient resources, or a missing volume/secret on the target nodes.

12Swarm 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.
# Portainer / Traefik / Shepherd 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

Networking & stacks

Ops & ecosystem

Cluster & Services

Networking & Stacks

Ops & Ecosystem

Worth memorizing