Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Docker Swarm mode is Docker Engine’s built-in cluster orchestrator. It turns multiple Docker hosts into one managed pool, where manager nodes maintain desired state and schedule tasks while worker nodes run containers. Use it when you deliberately want Swarm as your production runtime; use Docker Compose for non-Swarm deployments, and use Docker Desktop’s Kubernetes integration when your target is Kubernetes.

What Docker Swarm mode is

Swarm mode is an advanced feature of Docker Engine for managing a cluster of Docker daemons through the Docker CLI. It is different from Docker Classic Swarm, which Docker no longer actively develops.

A swarm consists of Engine hosts assigned manager, worker, or both roles. Managers store cluster state, elect leadership through the Raft consensus protocol, schedule work, and continually reconcile the actual cluster with the configuration you declare. Workers execute the tasks assigned to them and report their status.

The central object is a service. A service declares an image, command, replica count, networks, published ports, resource limits, placement rules, and update behavior. Swarm converts that declaration into one or more tasks; each task is the atomic scheduled unit that runs a container.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Managers, workers, and quorum

Manager responsibilities

  • Maintain the encrypted control-plane state.
  • Schedule service tasks onto suitable nodes.
  • Accept changes such as scaling, updates, and network creation.
  • Replace failed tasks when resources and placement rules permit.

Worker responsibilities

  • Run the containers assigned by managers.
  • Report task health and node status.
  • Join overlay networks and publish task endpoints as directed.

A node can be both manager and worker. For production, design manager count around failure tolerance: Docker recommends an odd number of managers so Raft can retain quorum. A single-manager swarm is suitable for testing. If that manager fails, already-running services can continue, but you cannot change cluster state until you create a replacement cluster or restore management availability. Continued container execution is not the same as a functioning control plane.

Create a swarm and add nodes

Prerequisites

  • Docker Engine installed on every host.
  • Stable hostnames or addresses and synchronized clocks.
  • Firewall rules allowing Swarm control, node communication, and overlay networking between hosts.
  • A manager address reachable by workers and additional managers.

Initialize the first manager

Run this on the host that will become the first manager:

docker swarm init --advertise-addr 10.0.0.10

Docker prints worker and manager join commands containing a token. Treat those tokens as credentials; regenerate them with docker swarm join-token --rotate worker or docker swarm join-token --rotate manager if exposed.

Join workers and additional managers

On a worker, run the worker command printed by initialization:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
docker swarm join --token <WORKER_TOKEN> 10.0.0.10:2377

To add a manager, use the manager token instead:

docker swarm join --token <MANAGER_TOKEN> 10.0.0.10:2377

Inspect membership from a manager:

docker node ls

Keep manager nodes on reliable infrastructure and avoid placing every manager in the same failure domain. Workers can be added for capacity without affecting Raft quorum.

Deploy a service

Replicated services

Replicated mode runs a declared number of interchangeable tasks. This example publishes port 8080 on the swarm and requests three web tasks:

docker service create 
  --name web 
  --replicas 3 
  --publish published=8080,target=80 
  nginx:latest

Check the desired and current state:

docker service ls
docker service ps web
docker service inspect web

If a worker disappears, managers attempt to schedule replacement tasks on available nodes until the requested replica count is restored. Placement constraints, resource reservations, unavailable images, and insufficient capacity can prevent immediate recovery.

Global services

Global mode places one task on every eligible node. It is useful for node-level agents such as monitoring or log collectors:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
docker service create 
  --name node-agent 
  --mode global 
  --mount type=bind,src=/var/log,dst=/host-log,ro 
  example/agent:1

Networks and resources

Create an overlay network for services that must communicate across hosts:

docker network create --driver overlay app-net

Declare CPU and memory expectations so scheduling can account for capacity:

docker service create 
  --name api 
  --network app-net 
  --replicas 4 
  --limit-cpu 1 
  --limit-memory 512M 
  --reserve-cpu 0.25 
  --reserve-memory 256M 
  example/api:1.4

Services on the same overlay network can discover one another by service name. For a stack-style deployment, define services in a Compose-format file and deploy it from a manager:

docker stack deploy -c stack.yml storefront

The exact Compose features accepted by Swarm differ from features intended only for local Compose, so validate the rendered configuration and inspect the resulting services.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Ingress, routing mesh, and external load balancers

Publishing a service port uses Swarm’s ingress overlay and routing mesh. An external client can reach a published port on a swarm node, and Swarm routes traffic to an available task, even when that task runs on another node. Services can also be placed behind an external load balancer, which can perform health-aware routing and TLS termination according to your architecture.

Overlay networking provides service-to-service connectivity and internal load balancing. It is separate from the application protocol itself: an HTTP request between containers is still HTTP unless your application uses TLS.

Rolling updates and rollback

Swarm can update tasks incrementally. By default, one task is updated at a time; make the behavior explicit for production:

docker service update 
  --image example/api:1.5 
  --update-parallelism 2 
  --update-delay 10s 
  --update-failure-action pause 
  --rollback-parallelism 1 
  --rollback-delay 5s 
  --rollback-failure-action pause 
  api

These controls determine how many tasks change concurrently, how long Swarm waits between batches, and whether a failed update pauses or takes another configured action. They do not guarantee zero downtime: readiness checks, connection draining, backward-compatible database migrations, and application-level health all remain your responsibility.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Observe progress with docker service ps api and docker service inspect --pretty api. If the new version is unhealthy, explicitly roll back:

docker service rollback api

Secrets and configuration

Swarm-managed secrets are encrypted in the control-plane store and made available only to services you authorize. A secret is mounted in the task rather than exposed as a normal environment variable:

printf '%s' 'production-password' | docker secret create db_password -
docker service create 
  --name database 
  --secret db_password 
  postgres:16

Standalone containers cannot consume Swarm secrets. A task that already received a secret can retain access during a temporary loss of swarm connectivity, but it cannot receive secret updates until it reconnects. Separate control-plane encryption from application-data encryption; overlay data encryption is an additional configuration and can have performance and networking implications.

Operational checks and failure recovery

Routine inspection

  • docker node ls — manager availability and node roles.
  • docker node inspect <node> — labels, reachability, and status details.
  • docker service ls — desired versus running replicas.
  • docker service ps <service> — task placement and error messages.
  • docker service logs <service> — aggregated service logs when logging configuration supports it.

Drain a node for maintenance

docker node update --availability drain worker-2

Swarm stops scheduling new work there and reschedules eligible tasks elsewhere. Return it to service with docker node update --availability active worker-2.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Common symptoms and fixes

  • Replica count stays below the target: inspect docker service ps; resolve image-pull failures, placement constraints, missing resources, or a drained node.
  • Node shows Down or Unreachable: verify host availability, firewall rules, advertised addresses, and Docker Engine logs. Do not remove a manager casually; removing one can destroy quorum.
  • Tasks repeatedly restart: run the image outside Swarm to verify its command and environment, then inspect task error output and health-check behavior.
  • Service name does not resolve: confirm both services share the same overlay network and that the caller is itself attached to that network.
  • Published port is unreachable: check host firewalls, the published-port definition, ingress connectivity, and whether any tasks are running.
  • Update pauses: inspect the failed task, fix the image or configuration, then continue with another update or run docker service rollback.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Swarm, Compose, or Kubernetes?

Question Choose Swarm when… Choose another option when…
Deployment target You want Docker Engine’s integrated multi-host production runtime. You are defining local or single-host workloads; Docker recommends Compose when no Swarm deployment is intended.
Control model You prefer services, tasks, managers, workers, and Raft in the Docker CLI. You need Kubernetes’ broader, portable and extensible platform model.
Development workflow Your development and production environments are intentionally Swarm-based. You are developing for Kubernetes; Docker points to Docker Desktop’s integrated Kubernetes feature.
Availability You can operate manager quorum, worker capacity, and recovery procedures. You cannot staff or design the required control-plane operations.

Kubernetes documentation describes a portable, extensible platform with service discovery, load balancing, and storage orchestration. Those descriptions support a high-level distinction, not a complete feature-by-feature verdict. Evaluate ecosystem integrations, migration effort, stateful-storage behavior, policy requirements, and team expertise for your own environment rather than assuming one orchestrator is universally simpler or more capable.

Performance, reliability, and cost considerations

  • Capacity: reserve CPU and memory for critical services and keep spare worker capacity for failover.
  • Network design: account for overlay encapsulation, cross-zone latency, published-port routing, and any additional overlay encryption overhead.
  • State: replicas do not make local container files durable. Use storage designed for your failure model and test restore procedures.
  • Updates: stage image changes, use conservative parallelism, and make schema migrations compatible with both old and new tasks.
  • Control plane: monitor manager health and quorum separately from application health; running containers can mask a broken management plane.
  • Cost: Swarm itself is a Docker Engine feature, but hosts, storage, networking, monitoring, backups, and operational labor still determine total cost.

Or skip the browser setup

If your deployment documentation needs a current screenshot of a dashboard or service, ScreenshotNeo provides a single HTTP call instead of maintaining browser automation. It accepts cookie and consent banners as a visitor, removes more than 60 known consent platforms plus newsletter popups and chat widgets before capture, and lets you turn each cleanup step off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and whether the request was billed.

It also offers an MCP server for Claude, Cursor, and other MCP clients, with take_screenshot, get_page_info, and capture_pdf tools. Features include full-page and CSS-selector captures, device presets, dark mode, retina scale, PDF controls, custom CSS and JavaScript, clicks, waits, request blocking, headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, configurable caching, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, and a usage API.

See the ScreenshotNeo API documentation for parameter details. cURL:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots, and every feature is included on every plan. Create a free ScreenshotNeo account.

Bottom line

Choose Swarm when its Engine-integrated service model, overlay networking, built-in updates, and operational scale match your team and production target. Design manager quorum deliberately, treat application health and data durability as separate concerns, and choose Compose or Kubernetes when your deployment target calls for them instead.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.