Docker Swarm Basics

Docker Swarm is Docker’s built-in cluster orchestrator. It lets several Docker Engines work together so you can declare services, replica counts, published ports, networks, and updates instead of manually starting individual containers. Swarm is simpler than Kubernetes and useful for learning orchestration because it uses the Docker CLI you already know.

Overview: How Docker Swarm Works

Swarm mode turns one or more Docker hosts into a cluster. A host in the cluster is called a node. A manager node stores cluster state, accepts service changes, runs the scheduler, and participates in the Raft consensus group that keeps the cluster’s desired state consistent. A worker node runs assigned tasks but does not make scheduling decisions. A single-machine learning swarm can have one manager and no separate workers, but production swarms normally use multiple managers for fault tolerance plus workers for application load.

The most important object in Swarm is a service. A service is not one container; it is a desired state. For example, docker service create --name web --replicas 3 nginx:1.27-alpine means “keep three tasks for this web service running somewhere in the cluster.” A task is Swarm’s scheduled unit of work. Each task usually results in one Docker container on a node. Underneath, Docker still pulls image manifests and read-only layers, creates a thin writable container layer, attaches networks and mounts, then starts the image’s configured process. Swarm changes placement and lifecycle, not the basic image/container model.

Swarm continuously compares desired state with actual state. If a task exits, a node disappears, or you change the replica count, the manager schedules work until actual state matches the service definition again. You usually inspect services with docker service ls and docker service ps, not by managing the generated containers directly. Containers created by Swarm are implementation details; deleting one by hand only makes Swarm create a replacement if the service still wants it.

Networking is also cluster-aware. Swarm can create overlay networks, which let service tasks on different Docker hosts communicate as if they are on one private network. Swarm also has a routing mesh for published ports: when you publish a service port, every node can accept traffic on that port and route it to a running task. This is convenient, but a production deployment still often uses an external load balancer or reverse proxy in front of the swarm.

Swarm is best for straightforward service orchestration: replicated stateless apps, controlled rolling updates, Docker-native secrets/configs, and multi-node scheduling with a smaller operational footprint than Kubernetes. It is not magic database clustering, automatic image building, or a full cloud platform. Stateful systems still need a storage and replication plan that matches the database or queue you are running.

Syntax

docker swarm init

docker swarm join --token TOKEN MANAGER_IP:2377

docker service create --name SERVICE --replicas REPLICAS --publish HOST_PORT:CONTAINER_PORT IMAGE

docker service ls

docker service ps SERVICE

docker service scale SERVICE=REPLICAS

docker service update --image IMAGE SERVICE

docker service rm SERVICE
Command or option Meaning
docker swarm init Enables Swarm mode on the current Docker Engine and makes it a manager node.
docker swarm join Adds another Docker host to the swarm using a join token generated by a manager.
--name SERVICE Gives the service a stable name used for inspection, DNS, updates, and removal.
--replicas REPLICAS Sets how many tasks Swarm should keep running for a replicated service.
--publish HOST_PORT:CONTAINER_PORT Publishes a port through Swarm’s routing mesh. This is what makes traffic reachable; EXPOSE in a Dockerfile is only metadata.
docker service ps Shows the tasks for a service, including desired state, current state, image, and node placement.
docker service scale Changes the desired replica count without editing individual containers.
docker service update Changes service configuration, commonly the image tag, and rolls tasks toward the new desired state.

Examples

Example 1: Initialize a Single-Node Swarm

For practice, a single Docker Engine can be both the whole cluster and the manager. This is the safest way to learn the commands without needing several machines.

docker swarm init

docker node ls

Output:

Swarm initialized: current node is now a manager.

ID                            HOSTNAME   STATUS    AVAILABILITY   MANAGER STATUS   ENGINE VERSION
m7abc123def456ghi789jklmn *   dockerbox  Ready     Active         Leader           26.1.0

The current Docker Engine becomes a manager. On a real multi-node cluster, Docker prints a docker swarm join command containing a token for adding workers. The manager stores desired state and schedules tasks; in this one-node example, it also runs the tasks itself.

Example 2: Create and Inspect a Replicated Service

This creates three Nginx tasks and publishes container port 80 on host port 8080. The image tag is pinned to nginx:1.27-alpine instead of latest so every deploy refers to a known version.

docker service create --name web --replicas 3 --publish 8080:80 nginx:1.27-alpine

docker service ls

docker service ps web

Output:

ID             NAME      MODE         REPLICAS   IMAGE                PORTS
p9example123   web       replicated   3/3        nginx:1.27-alpine    *:8080->80/tcp

ID             NAME      IMAGE                NODE       DESIRED STATE   CURRENT STATE
x1example111   web.1     nginx:1.27-alpine    dockerbox  Running         Running 18 seconds ago
x2example222   web.2     nginx:1.27-alpine    dockerbox  Running         Running 18 seconds ago
x3example333   web.3     nginx:1.27-alpine    dockerbox  Running         Running 18 seconds ago

Swarm creates tasks, and each task runs a container from the Nginx image. On one node, all three land on the same host. On a larger swarm, the scheduler can spread them across available nodes. The REPLICAS column shows whether the cluster has reached the desired count.

Example 3: Scale and Roll a Service

You change services by changing desired state. Do not manually start extra containers to scale a Swarm service.

docker service scale web=5

docker service update --image nginx:1.27-alpine web

docker service ps web

Output:

web scaled to 5
web
overall progress: 5 out of 5 tasks
verify: Service converged

ID             NAME      IMAGE                NODE       DESIRED STATE   CURRENT STATE
r1example111   web.1     nginx:1.27-alpine    dockerbox  Running         Running 8 seconds ago
r2example222   web.2     nginx:1.27-alpine    dockerbox  Running         Running 8 seconds ago
r3example333   web.3     nginx:1.27-alpine    dockerbox  Running         Running 8 seconds ago

Scaling to five tells the manager to schedule two additional tasks. Updating the image, even to the same tag for demonstration, goes through Swarm’s update machinery. In real deployments, you update from one tested tag to another, such as myapp:1.0.0 to myapp:1.0.1, and Swarm gradually replaces old tasks.

Example 4: Use an Overlay Network

Overlay networks let services communicate privately across nodes. This example creates an attachable overlay and places a web service on it.

docker network create --driver overlay app-net

docker service create --name api --replicas 2 --network app-net nginx:1.27-alpine

docker service inspect --format '{{.Spec.TaskTemplate.Networks}}' api

Output:

a1networkexample
api
[{a1networkexample  []}]

Every task for api joins app-net. Other services on the same overlay can resolve api by service name using Docker’s embedded DNS. This is different from a normal single-host bridge network because overlay networking can span multiple Docker hosts in the swarm.

How It Works Step by Step

  1. You run docker swarm init. Docker enables Swarm mode, creates a manager, generates join tokens, and starts maintaining cluster state.
  2. You create a service. The manager records the service spec: image, replica count, ports, networks, mounts, environment, and update behavior.
  3. The scheduler chooses nodes for tasks based on availability, constraints, resource reservations, and current cluster state.
  4. Each selected node receives a task assignment. The local Docker Engine pulls the image manifest and required read-only layers if they are missing.
  5. Docker creates a container for the task with its own writable layer, joins requested networks, applies mounts and runtime settings, and starts the main process.
  6. The node reports task status back to the manager. If a task fails or a node becomes unavailable, the manager schedules replacement work when the service still requires replicas.
  7. When you scale or update the service, Swarm changes the desired state and reconciles toward it. You manage the service, and Swarm manages the task containers.

Common Mistakes

Managing Swarm Containers by Hand

Wrong:

docker rm -f web.1.x1example111

A Swarm task container is controlled by the service. Removing it manually does not scale the service down; Swarm sees a missing task and creates a replacement. Fix the desired state instead:

docker service scale web=2

docker service rm web

Using latest in a Cluster

Wrong:

docker service create --name web --replicas 3 nginx:latest

latest is a moving tag. Different nodes may pull it at different times, and a later redeploy may not mean the same image contents. Use a tested, pinned tag such as nginx:1.27-alpine, or pin by digest when you need strict reproducibility.

Assuming EXPOSE Publishes a Swarm Service

A Dockerfile line like EXPOSE 80 documents that the image expects traffic on port 80, but it does not publish anything to users. In Swarm, publish traffic with docker service create --publish 8080:80 ... or a stack file’s port publishing. Metadata is not a network route.

Scaling a Database Without Database Clustering

Wrong:

docker service create --name db --replicas 3 postgres:16-alpine

This creates three PostgreSQL containers, not one safe PostgreSQL cluster. Stateful systems need official replication, stable storage, backups, and failover design. For many applications, the pragmatic answer is to run stateless services in Swarm and use a managed database outside the cluster.

Best Practices

  • Use Swarm services as the management boundary. Inspect and change services, not generated task containers.
  • Run at least three manager nodes for a production swarm so manager consensus can survive one manager failure.
  • Keep replicated services stateless where possible. Put durable data in named volumes, external storage, or managed databases designed for failure recovery.
  • Pin image tags and promote tested images through environments. Avoid latest for services.
  • Use overlay networks to keep service-to-service traffic private, and publish only the ports that need external access.
  • Use docker service ps, docker service logs, and docker node ls when troubleshooting placement and health.
  • Use Docker secrets or the platform secret store for sensitive values. Do not bake passwords or API keys into images with ENV; image layers can preserve deleted data.
  • Test rolling updates and rollbacks before relying on them during an incident.

Practice Exercises

  1. Initialize a single-node swarm and create a three-replica nginx:1.27-alpine service named web. Expected end state: docker service ls shows 3/3 replicas.
  2. Scale the web service from three replicas to one, then inspect task history with docker service ps web. Hint: notice that Swarm records old tasks as well as current ones.
  3. Create an overlay network named app-net and attach a two-replica service to it. Expected end state: service inspection shows the service joined to the overlay network.

Summary

  • Docker Swarm mode is Docker’s built-in orchestrator for managing services across one or more Docker Engines.
  • Managers store desired state and schedule tasks; workers run assigned tasks.
  • A service declares the desired image, replica count, networks, ports, and runtime settings. Tasks are the scheduled container work.
  • Swarm reconciles actual state to desired state, replacing failed tasks and applying scale or update changes.
  • Overlay networks and published service ports provide cluster-aware networking, but production ingress still needs deliberate design.
  • Use pinned images, service-level commands, secret management, and a real storage plan for stateful systems.