Introduction

Docker Swarm is Docker's native container orchestration platform that allows you to deploy, manage, scale, and monitor containerized applications across multiple Docker hosts.

Docker Swarm turns a group of Docker hosts into a single virtual cluster that can be managed as one system. It provides features such as scaling, load balancing, service discovery, fault tolerance, and high availability.

Docker Swarm is commonly used for:

Container Orchestration
Microservices Applications
High Availability Deployments
Load Balancing
Distributed Systems
Multi-Host Container Management

Why Docker Swarm?

Docker works well for managing containers on a single server.

However, production environments often require:

Multiple Servers
High Availability
Automatic Failover
Horizontal Scaling
Load Balancing
Centralized Management

Docker Swarm addresses these challenges by allowing multiple Docker hosts to work together as a cluster.

Benefits:

Easy Cluster Management
Built-in Load Balancing
Automatic Service Discovery
Rolling Updates
High Availability
Fault Tolerance
Horizontal Scaling

Docker Compose vs Docker Swarm

Feature	Docker Compose	Docker Swarm
Environment	Single Host	Multiple Hosts
Scaling	Limited	Built-in
Load Balancing	No	Yes
High Availability	No	Yes
Service Discovery	Basic	Built-in
Production Ready	Small Deployments	Distributed Deployments

Docker Compose is primarily used for managing containers on a single machine, while Docker Swarm is used for orchestrating containers across multiple servers.

Docker Swarm Architecture

                                   Swarm Cluster

                                   Manager Node
                                             |
        ┌─────────────────┼─────────────────┐
        ▼                                  ▼                                 ▼

     Worker-1                     Worker-2                       Worker-3

        |                                    |                                   |
   Containers                    Containers                     Containers

A Docker Swarm cluster consists of manager and worker nodes.

Manager nodes control and orchestrate the cluster, while worker nodes execute container workloads.

Key Concepts

Swarm Cluster

A group of Docker hosts working together as a single system.

These hosts can be:

Physical Servers
Virtual Machines
Cloud Instances

Nodes

Nodes are Docker engines participating in the swarm.

There are two types:

Manager Nodes

Responsible for:

Cluster Management
Scheduling
Orchestration
Maintaining Desired State

Worker Nodes

Responsible for:

Running Containers
Executing Assigned Tasks

Worker nodes do not make scheduling decisions.

Services

A service defines how containers should run in the cluster.

Example:

docker service create nginx

A service specifies:

Docker Image
Number of Replicas
Network Configuration
Resource Constraints

Tasks

A task is a running container instance created by a service.

Each task is assigned to a node in the swarm cluster.

Overlay Networks

Docker Swarm creates overlay networks that allow containers running on different hosts to communicate securely.

Benefits:

Cross-Host Communication
Service Discovery
Simplified Networking

Load Balancing

Docker Swarm automatically distributes incoming requests across service replicas.

Benefits:

Better Resource Utilization
Improved Availability
Fault Tolerance

Scaling

Services can be scaled up or down using a single command.

Example:

docker service scale my-nginx=10

Docker Swarm automatically distributes replicas across available nodes.

Service Discovery

Containers can communicate using service names.

Example:

my-nginx

instead of

192.168.1.20

State Management

Docker Swarm continuously ensures the desired state of services is maintained.

If a container or node fails, Docker Swarm automatically recreates workloads.

Docker Swarm Workflow

1. Create Swarm Cluster
2. Add Manager and Worker Nodes
3. Deploy Services
4. Scale Services
5. Perform Rolling Updates
6. Monitor and Manage Cluster

Example 1: Setting Up a Docker Swarm Cluster and Deploying a Service

In this example, we will create a Docker Swarm cluster using three AWS EC2 instances and deploy an Nginx service.

Step 1: Create EC2 Instances

Create three AWS EC2 instances (One for manager node and two for worker nodes)

Example:

Manager Node
Worker Node 1
Worker Node 2

Ensure port 2377 is allowed in the security groups.

Port 2377 is used for swarm cluster management.

Step 2: Initialize Swarm Cluster on your Manager Node

Run on the manager node:

docker swarm init

Docker generates a swarm join token.

Save the generated token. You will need it to add worker nodes to the swarm cluster.

Step 3: Add Worker Nodes to Swarm Cluster

Run on worker nodes:

docker swarm join --token <SWARM_JOIN_TOKEN> <MANAGER-IP>:2377

This adds worker nodes to the swarm cluster.

You can also add additional Manager Nodes to Swarm Cluster

👉 To add another manager node to the swarm, run the following command on an existing manager node:

docker swarm join-token manager

This command generates a manager join command. Run the generated command on the node that you want to add as a manager node.

Step 4: List all nodes in Swarm Cluster

List all nodes in swarm cluster, run the following command on manager node. It will show various details of swarm cluster nodes such as which are manager (leader), which are worker nodes:

docker node ls

Displays:

Node IDs
Hostnames
Roles
Availability
Leader Node

Step 5: Deploy a service (e.g. Nginx Docker Container) to the Swarm Cluster.

Run this command on manager node:

docker service create --name my-nginx -p 80:80 nginx

Note: The manager node schedules the service, but Docker Swarm may deploy the container on any eligible node (manager or worker) depending on cluster state and scheduling decisions.

Step 6: Verify the Deployed Service

Verify the service (e.g. nginx) is running and the replicas (if any) are spread across nodes.

Run this command on manager node

List services:

docker service ls

View detailed replica information:

docker service ps my-nginx

Displays:

Replica Status
Assigned Nodes
Running Tasks

Step 7: Scale the Service

You can scale the number of replicas up or down.

Run the following command on manager node. It will scale to two replicas:

docker service scale my-nginx=2

Docker Swarm automatically distributes replicas across available nodes.

Verify:
👉 To check on which nodes of swarm cluster these two replicas are deployed, fire the following command on manager node. You can see the nodes on which the service replicas are deployed. This command provides insight into the state of individual replicas, their assigned nodes, and their statuses.
docker service ps <SERVICE-NAME>
docker service ps my-nginx
Displays where replicas are deployed.

Note: Let's say we deploy 5 replicas (containers) of a service to swarm cluster but currently our swarm cluster has only three nodes (VMs) than in this case Docker Swarm automatically distributes replicas across available nodes. The exact placement depends on resource availability, scheduling decisions, placement constraints, and cluster state. A common distribution in a three-node cluster may be two replicas on one node, two on another, and one on the third node.

Try it,
docker service scale my-nginx=5
docker service ps my-nginx
docker ps (run this command on each nodes to check no. of running containers)

Step 8: List Running Containers

Run on any node (Managers or Workers):

docker ps

Displays containers currently running on that node.

Step 9: Update a Service

Run this command on manager node.

To update the service (e.g., change the image version)

docker service update --image nginx:latest my-nginx

Step 10: Promote a worker node to a manager node

Once a node has joined the swarm as a worker, it can be promoted to a manager using the following command,

docker node promote <NODE-ID>

To get the NODE-ID fire command 'docker node ls'

You can always demote a manager node back to a worker node using following command,

docker node demote <NODE-ID>

Step 11: Set Node Availability (Drain, Pause, or Active)

Worker nodes can have their availability changed by a manager node.

Drain: No new tasks will be scheduled on the node and existing tasks are moved to other available nodes.

docker node update --availability drain <NODE-ID>

Pause: No new tasks will be scheduled on the node, but existing tasks continue running.

docker node update --availability pause <NODE-ID>

Active: The node can accept and run tasks normally.

docker node update --availability active <NODE-ID>

Step 12: Check all tasks (containers) running on a specific worker node, from a manager node

docker node ps <NODE-ID>

Step 13: Inspect Nodes and Services

Inspect a particular node

docker node inspect --pretty <NODE-ID>

Inspect a particular service

docker service inspect --pretty <SERVICE_NAME>

Get information of your docker swarm cluster

docker info

Step 14: Remove Service (e.g. Nginx Docker Container) from swarm nodes

Run this command on manager node:

docker service rm my-nginx

Removes the service and all associated containers.

Step 15: Leave a Worker Node from the Swarm Cluster

Run this command on the worker node.

docker swarm leave

Both worker nodes are down now, see status

A manager node can remove a worker node from the swarm using following command but before removing, ensure that the worker node has left the swarm (docker swarm leave)

docker node rm <NODE-ID>

Step 16: Leave a Manager Node from the Swarm Cluster

docker swarm leave --force

If a manager node leaves the swarm cluster than anther manager node take the charge as manager but suppose there is no another manager node in the swarm cluster than complete swarm cluster will be removed.

Step 17: Get help for any Docker command or sub-command:

docker <COMMAND> --help
docker <COMMAND> <SUBCOMMAND> --help

e.g.

docker node --help

docker node update --help

Example 2: Deploy a stack (multiple services) using docker compose on docker swarm

Docker Swarm supports deploying multiple services using Docker Compose files.

👉 In this basic example we will see how to use docker compose tool for docker swarm cluster.

mkdir my_workspace

cd my_workspace

Step 1: Initialize docker swarm cluster on your manager node

docker swarm init

Step 2: Add worker nodes to swarm cluster.

Run the following command on each worker node that you want to add to the swarm cluster.

docker swarm join --token <SWARM_JOIN_TOKEN> <MANAGER-IP>:2377

Step 3: Create docker-compose.yml

services:
  web:
    image: nginx
    ports:
      - "80:80"

  mydb:
    image: postgres
    environment:
      POSTGRES_PASSWORD: test123

Step 4: Deploy a stack (multiple services) using a docker-compose.yml file in swarm cluster

docker stack deploy --compose-file <FILE> <STACK-NAME>
docker stack deploy --compose-file docker-compose.yml my-stack

Deploys all services defined in the Compose file as a single stack in the swarm cluster.

Step 5: List all stacks deployed in the swarm cluster

docker stack ls

Displays all stacks currently deployed in the swarm cluster.

Step 6: List all services within a stack

docker stack services <STACK_NAME>

docker stack services my-stack

Displays all services running within the stack.

Step 7: View stack tasks

You can view detailed information about stack tasks, including which service replicas are deployed on which swarm nodes.

docker stack ps my-stack

Displays:

Tasks
Assigned Nodes
Replica Status

Step 8: Inspect stack services

docker service ls

Displays all services created by the deployed stack.

docker stack services my-stack

Displays services belonging only to the specified stack.

Step 9: Remove stack

docker stack rm my-stack

Removes the stack and all services, containers, and networking resources associated with the stack.

Docker Swarm Commands Cheat Sheet

Command	Description
docker swarm init	Initialize swarm cluster
docker swarm leave	Leave swarm cluster
docker swarm leave --force	Force manager to leave cluster
docker node ls	List swarm nodes
docker node promote	Promote worker to manager
docker node demote	Demote manager to worker
docker node ps	Display tasks running on a node
docker node inspect	Inspect node information
docker service create	Create a service
docker service ls	List services
docker service ps	Display service tasks
docker service scale	Scale service replicas
docker service update	Update service
docker service inspect	Inspect service
docker service rm	Remove service
docker stack deploy	Deploy stack
docker stack ls	List stacks
docker stack services	List stack services
docker stack ps	Display stack tasks
docker stack rm	Remove stack
docker info	Display swarm information

Docker Swarm and Raft Consensus Algorithm

Docker Swarm uses the Raft Consensus Algorithm to manage cluster state.

Leader Node

Raft selects a leader node responsible for managing the swarm.

Leader Election

If the leader fails, Raft automatically elects a new leader.

Cluster State Synchronization

Raft ensures all manager nodes maintain the same cluster state.

Fault Tolerance

Raft can tolerate up to:

(N - 1) / 2

manager node failures.

Examples:

Manager Nodes	Supported Failures
3	1
5	2
7	3

Docker Swarm Benefits

Easy Setup
Native Docker Integration
Built-in Load Balancing
Service Discovery
Rolling Updates
Horizontal Scaling
High Availability
Fault Tolerance

Docker Swarm Limitations

Smaller Ecosystem than Kubernetes
Fewer Advanced Features
Less Popular for Large Enterprise Deployments
Limited Extensibility

Docker Swarm vs Kubernetes

Feature	Docker Swarm	Kubernetes
Setup Complexity	Easy	Moderate to High
Learning Curve	Easy	Steep
Installation	Simple	Complex
Ecosystem	Smaller	Large
Enterprise Adoption	Moderate	Very High
Scalability	Good	Excellent

Conclusion

Docker Swarm is Docker's native container orchestration platform that enables deployment and management of containerized applications across multiple servers.

In this guide, we covered:

Docker Swarm Fundamentals
Swarm Architecture
Manager and Worker Nodes
Services and Tasks
Scaling
Service Discovery
Load Balancing
Docker Stack
Raft Consensus Algorithm
Common Commands
Best Practices

Docker Swarm provides a simple entry point into container orchestration and helps developers understand concepts such as clustering, scheduling, scaling, and high availability before moving to Kubernetes.