I run a couple of small services on a single box with a plain docker-compose.yaml and restart: unless-stopped, and every so often I read that Swarm mode gives you rolling deploys and self-healing for free, built into the engine I already have, no extra tooling. I'd never actually tried it on the kind of single machine I actually run things on, rather than a cluster. So I built a small two-service app, ran it under Compose, then moved the exact same file into Swarm mode and measured what changed.
The short version: the compose file needed editing before Swarm would take it at all, scaling past one replica looked successful and wasn't, and the thing that actually surprised me was restart behaviour, not rolling updates.
The setup
A tiny Python HTTP server behind a Redis cache, built from one Dockerfile:
services: web: build: ./app image: dp-swarmdemo-web:v1 ports: - "8000:8000" env_file: [./app.env] healthcheck: test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000')"] interval: 2s timeout: 2s retries: 3 depends_on: cache: condition: service_healthy restart: unless-stopped cache: image: redis:7-alpine healthcheck: { test: ["CMD", "redis-cli", "ping"], interval: 2s, timeout: 2s, retries: 3 } restart: unless-stopped docker compose up -d --build from cold brought both containers up, healthy, in 10.7 seconds. curl localhost:8000 answered immediately. Nothing unusual yet.
The file Swarm half-rejects
docker swarm init on the same machine took 0.65 seconds. Then I ran the exact file above through docker stack deploy -c compose.yaml dp, expecting it to just work since it's valid Compose YAML.
It refused outright:
services.web.depends_on: must be a list Swarm's stack parser doesn't understand the long-form depends_on with a condition, only the short list form. That's a real edit, not a warning, so I changed it to depends_on: [cache] and tried again. That got further, but with a warning:
Ignoring unsupported options: build, restart build: is ignored because Swarm only ever pulls or uses a locally tagged image across the whole cluster; it has no concept of building one. restart: is ignored because Swarm manages task supervision itself through deploy.restart_policy, which my file never set, so it fell back to a default of {"Condition":"any","Delay":5s,"MaxAttempts":0} — restart on anything, always wait five seconds, never give up. I hadn't asked for that policy, I'd just inherited it by not specifying one.
Neither of these stopped the stack from coming up. Both of them are the kind of thing that only shows up the first time you actually run stack deploy against a file written for Compose, not from reading about the two side by side.
Scaling looked fine and wasn't
Under Compose, scaling the web service to two replicas with the fixed host port still in the file failed immediately, with an error that tells you exactly what's wrong:
Bind for 0.0.0.0:8000 failed: port is already allocated Fair enough — one container can hold a host port, two can't, and Compose says so straight away. Under Swarm, docker service scale dp_web=3 did not refuse. It reported 3/3, docker service ls agreed, and docker service ps showed all three tasks Running. Then curl localhost:8000 came back Connection reset by peer, every time, for all ten tries.
This is where I nearly wrote down "Swarm's routing mesh doesn't work," which would have been the wrong conclusion about Swarm and the right one about this machine. The routing mesh load-balances a published port across replicas with IPVS, a Linux kernel feature. lsmod and /proc/modules on this host had nothing matching ip_vs at all — the module isn't there. The iptables -t nat rule for port 8000 existed and pointed at an address, but nothing was listening behind it, because the piece that was meant to do the listening never loaded. Each container was healthy and individually reachable from inside its own network namespace; the shared entry point for the service was not. This is specific to a kernel that lacks IPVS — a stock Linux host won't hit it — but it's exactly the kind of host you might be running Swarm on without knowing it: a minimal cloud image, a restricted container, a hardened kernel. docker service ls gave no hint that anything was wrong.
The documented workaround, and its own ceiling
Swarm's docs are honest that dnsrr endpoint mode skips the load-balanced VIP, so I tried it as a way round the missing module:
EndpointSpec: port published with ingress mode can't be used with dnsrr mode Rejected outright — you can't combine a published port with dnsrr, full stop. The actual documented alternative is mode: host on the port, which skips the mesh entirely and binds the container straight to the node's own port. That worked: one replica, curl answered 200 again. But a single host port can only be bound once per node, and I only had one node, so scaling back up to three replicas left two tasks sitting in Pending forever:
no suitable node (host-mode port already in use on 1 node) Swarm's own "safer rollout" setting ran into the identical wall. I set update_order: start-first, so the new task would come up before the old one was stopped, and pushed a new image tag. The deploy never finished — the incoming task wanted the same host port the outgoing one still held, so it sat in Pending with the same "port already in use" error, while the old task kept serving. I had to run docker service update --rollback to get out of it. On a single node with a port published this way, every one of Swarm's multi-replica safety features is exactly what you don't have.
What actually surprised me: restarts, not rollouts
I killed the running web task outright, docker kill on its container ID, to see how fast Swarm would replace it. 5.98 seconds, matching that default policy almost exactly: 5 seconds of mandatory delay plus the time to start a fresh container.
Then I ran the same kill against a plain docker run --restart unless-stopped container of the same image, outside Swarm, expecting a similar recovery. It never came back. docker inspect showed RestartCount: 0, exit code 137, state exited, over two minutes later. The daemon's own log explained why, logged at the exact moment the container died: stopping restart-manager. This isn't a bug — Docker's restart policies are explicit that a container stopped through the API, kill included, is treated the same as a deliberate stop, and unless-stopped means exactly what it says: it won't restart something that was, as far as Docker's concerned, stopped on purpose. I'd read that line in the docs before and still didn't expect it to apply to a kill -9-equivalent, which feels like a crash from the outside.
Swarm doesn't have this gap, because it isn't using the per-container restart manager at all. It watches desired replica count against actual running tasks and reschedules the difference, regardless of how the old task died. That difference, not the rolling-update story, is the strongest practical case I found for Swarm supervising a service I actually depend on staying up.
The one number that went the wrong way
I also wanted a before-and-after on deploy downtime, since that's the headline Swarm is supposed to win on. Compose's recreate-based update (stop, remove, recreate on a one-line code change) dropped 5 of 400 probes sent every 20ms, about 1.25%. Swarm's default stop-first rolling update, still capped at one replica by the port problem above, produced a continuous 1.15-second gap and failed 31 of 527 probes sent every 30ms, about 5.9%. Worse, not better. With more than one working replica this would very likely flip, since that is the entire point of a rolling update — but I couldn't demonstrate that on this host, and I'd rather say that plainly than imply a result I didn't actually get.
What I got wrong on the way
My first attempt at that last measurement said zero dropped requests for the Swarm update, which looked like a clean win and made no sense next to a 22-second docker service update command. My probe loop ran a fixed 300 iterations at 20ms apiece, about six seconds, and finished before the actual container swap happened deeper into that 22 seconds. The harness had stopped watching before the thing I was measuring occurred. I reran it with timestamped output long enough to cover the whole update and found the real gap sitting at the 13-to-14-second mark. A measurement that shows no effect is a reason to check the measurement before it's a reason to write the sentence "no difference."
Run it yourself
mkdir app && printf 'FROM python:3.13-slim\nCOPY server.py /server.py\nCMD ["python3","/server.py"]\n' > app/Dockerfile # server.py: any script that serves something on :8000 docker compose up -d --build curl localhost:8000 docker swarm init docker stack deploy -c compose.yaml dp # edit depends_on to a list first docker service scale dp_web=3 docker service ps dp_web # watch for routing-mesh or scheduling errors docker service update --image dp-swarmdemo-web:v2 dp_web docker service inspect dp_web --format '{{json .Spec.TaskTemplate.RestartPolicy}}' Where I landed
That docker kill result bothered me enough to check one more thing: whether a plain shell loop around docker run would survive the same kill, since that's roughly what I'd been trusting restart: unless-stopped to do for me. while true; do docker run --rm --name loop-web -p 8000:8000 dp-swarmdemo-web:v1; done, running in the background, came back in 1.45 seconds after the same docker kill — faster than Swarm's 5.98, and unlike the --restart policy, it actually came back at all. A shell loop doesn't know or care that anything called an API to stop the container; it only sees the process it's waiting on exit, and starts the whole thing again. That's a dumber tool than restart: unless-stopped, and on this one point it beat both alternatives.
docker swarm init on this one box is staying off. Nearly every error in this post traces back to there being one node to schedule onto: one port to bind, one place for a replica to land, one node for start-first to need a second slot on. None of that is Swarm being broken; it's Swarm's whole model assuming you brought more than one machine. If a second box shows up, I'll run this again, because that's the point at which the port fights stop happening and the failover is supposed to actually kick in.

