Master Docker Swarm: Core Concepts, Modes, and Essential Commands

Docker Swarm is Docker's built‑in container‑cluster management service, included since Docker 1.12.0 and also called Swarm Mode.

Compared with Kubernetes, Docker Swarm is simpler and fully compatible with docker‑compose, making it a good entry point for beginners.

Concepts

Docker Swarm consists of the following concepts:

Swarm

Node

Stack

Service

Task

Load balancing

Swarm refers to a cluster of computers linked by Docker. The docker swarm command creates, joins, or leaves a cluster.

A Node is a Docker host and can be a Manager or a Worker. At least one Manager is required; only Managers can run management commands, while both Managers and Workers can run Services.

A Stack is a group of Services, similar to docker‑compose. By default a Stack shares a single Network that isolates it from other Stacks.

A Service represents a set of containers. Services can run in replicated mode (a fixed number of containers) or global mode (one container on every eligible Node).

A Task is the smallest unit of work—a single container instance that executes a Service.

Load balancing in Swarm uses an Ingress network; accessing any node’s published port is automatically routed to the appropriate Service.

Modes

Replicated Mode

services:
  some-service:
    ...
    deploy:
      mode: replicated
      replicas: 3

When mode is omitted, replicated with a single replica is the default.

Global Mode

services:
  some-service:
    ...
    deploy:
      mode: global
      placement:
        ...

In global mode a container is scheduled on every eligible Node; placement constraints can limit which Nodes receive the container.

Common Operations

Create the First Node

docker swarm init --advertise-addr $IP

$IP is the external IP of the node, allowing other nodes to join. After this command the Swarm has a single Manager.

Add a New Node

On a Manager, run:

docker swarm join-token manager
# copy the displayed command and run it on the new node:
docker swarm join --token SWMTKN-... <manager_ip>:2377

docker swarm join-token worker
# copy the displayed command and run it on the new node:
docker swarm join --token SWMTKN-... <manager_ip>:2377

Running the join command on a machine that is not part of any Swarm adds it as a Manager or Worker.

Set Node Labels

docker node update $node_name --label-add main=true

Labels are key‑value pairs; they can be used in a Compose file’s placement.constraints to restrict services to nodes with a matching label.

Deploy a Stack

docker stack deploy $stack_name -c docker-compose.yaml -c other.yaml ...

$stack_name is the name of the Stack. Multiple compose files can be supplied; the syntax is the same as with docker‑compose plus Swarm‑specific options.

Remove a Stack

docker stack rm $stack_name

Update a Service Image

docker service update --image $image:$tag $service_name