Docker Swarm

Docker Swarm: Single Node to Multi-Node

Compose and Swarm read the same file and interpret it differently. The trap is that Swarm fails silently: the stack deploys, containers start, and something just doesn't work the way it did locally. Write the compose file for the multi-node world from day one and the single-node case still works.

The mental model: a container is a process, not a computer

Swarm tears down and recreates containers constantly, on every update, node failure, scale, and rebalance. The new container has a new ID, a new IP, a new hostname, and a blank filesystem. Treat the container as disposable and keep all state outside it: a database or Redis for sessions, a named volume or object storage for files, env or Docker secrets/configs for configuration, stdout/stderr for logs. The test: if Swarm kills this container right now and starts a new one, does the app work identically? If not, state is leaking into the container.

Directives Swarm silently ignores

docker stack deploy reads these and skips them with no error. If you relied on one locally, you debug for hours before realizing Swarm never read it.

build (Swarm only runs pre-built registry images), container_name (names collide with replicas), depends_on (no startup ordering, services start in parallel), links, restart (use deploy.restart_policy), networks.ipv4_address / ipv6_address, network_mode, cap_add / cap_drop, devices, tmpfs, extra_hosts, sysctls, security_opt, cgroup_parent, userns_mode. Capabilities, sysctls, and security options are set at the engine level on each node instead.

Directives that change behavior in Swarm

• ports publish through the routing mesh: the port opens on every node, and traffic to any node is routed to a container wherever it runs. Publish the container port only (- "61339") and let the mesh assign a host port, your reverse proxy reaches the service by name and never needs to know the host port.
• volumes: named volumes work everywhere; bind mounts to host paths break the moment a container is scheduled on a different node, because that path doesn't exist there. Use named volumes for data and Docker configs/secrets for files.
• networks: Compose defaults to bridge (single host). Swarm needs overlay (multi-host). A bridge network in a stack means services can't talk across nodes.

Never hardcode an IP, the service name is the identity

Container IPs change on every restart, scale, and update. The service name is the one thing that never changes; Docker DNS resolves it to wherever the container currently lives. Hardcoding an IP breaks replicas, load balancing, and multi-node, but the worst case bites with a single replica during a routine rolling update: the new container needs an IP the dying old container hasn't released yet, and you can deadlock, the new one waits for the IP, the old one waits to be healthy, the update hangs, and rollback hits the same conflict. Connect by name (mongodb://mongo:27017/mydb) and none of it happens. A reverse proxy in the mesh needs a Docker-aware DNS resolver with a short TTL so it re-resolves names, see the nginx skill.