Install Docker Swarm Cluster on Debian 10 -Step by Step Process ?

Docker Swarm is a tool that allows you to deploy a cluster of Docker Hosts. It's a native clustering tool provided by Docker which provides high-availability and high-performance for your application by distributing it to all nodes inside the swarm cluster.

Here at Ibmi Media, as part of our Server Management Services, we regularly help our Customers to perform related Docker queries.

In this context, we shall look into steps to install Docker Swarm Cluster on Debian 10.

How to Install Docker Swarm Cluster on Debian 10 ?

To perform Docker Swarm Cluster Installation procedure, you can follow the steps below:

  • Node preparation.
  • Install Docker CE on Debian 10.
  • Initialize Docker Swarm Cluster.
  • Deploy Applications on Docker Swarm.
  • Scale Applications on Docker Swarm.

1. Node preparation

Initially, we need to configure the hostnames for each node in the /etc/hosts file for local resolution:

$ sudo vim /etc/hosts

Add the details of the nodes on each server, both the manager and the worker nodes: manager worker-01 worker-02

Ensure that the hosts can reach each other via ping.

2. Install Docker CE on Debian 10

Once the node preparation is over, we need to install Docker engine on all the hosts, manager and worker nodes.

First, install dependency packages on the hosts:

$ sudo apt-get update
$ sudo apt-get install apt-transport-https ca-certificates curl gnupg-agent software-properties-common

Then, we need to add Docker GPG key:

$ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -

Next, we will add Docker repository:

$ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable"

After adding the repository, we can install Docker Engine:

$ sudo apt-get update
$ sudo apt-get install docker-ce docker-ce-cli

Then, start and enable Docker:

$ sudo systemctl start docker
$ sudo systemctl enable docker

After that, add the user to docker group:

$ sudo usermod -aG docker ${USER}

3. Initialize Docker Swarm Cluster

Here, we need to initialize Docker swarm mode on the manager node. Then we add the worker nodes later.

The command below is used to initialize Docker Swarm Manager. We should replace the <manager-IP> address with the IP of manager node.

$ newgrp docker
$ sudo docker swarm init --advertise-addr <manager-IP>

Sample output:

$ docker swarm init --advertise-addr

With the manager node initialized, we can now add the worker nodes using the join-token that is given in the sample above.

$ docker swarm join --token SWMTKN-1-5yat7zlum78qmnlhv1vs0b0k4c42jafh5kt8xtb36eara4c5ip-490dr4yhpbe5qnic476wh90zg
This node joined a swarm as a worker.

We can check if the worker nodes have joined to cluster successfully using the command below:

$ sudo docker node ls

4. Deploy Applications on Docker Swarm

Here, we will deploy a web application on our cluster.

$ docker service create --name webserver -p 8080:80 nginx

The above command deploys Nginx application on the cluster and exposes on port 8080.

To confirm if the service is running use the command below:

$ docker service ls

5. Scale Applications on Docker Swarm

We can scale applications on Docker Swarm Cluster for high availability and high performance.

The command below helps with this:

$ docker service scale webserver=4

Where webserver=4 is the name of the application and the number of total containers to be up after the replication.

We can verify the replicas with the command below:

$ docker service ls

We have successfully deployed our Docker Swarm cluster on Debian 10 hosts.

How to resolve Common errors with the install of Docker Swarm Cluster on Debian 10 ?

1. Error response from daemon: rpc error: code = 9 desc = node node9 is not down and can’t be removed

This error occurs while removing a node from a swarm. In most cases, we should shut down a node before removing it from a swarm with the command:

docker node rm

Usually, we will remove a node from a swarm, if a node becomes unreachable, unresponsive or compromised. For instance, if node9 becomes compromised:

$ docker node rm node9
Error response from daemon: rpc error: code = 9 desc = node node9 is not down and can't be removed

We can resolve this by forcefully removing the node without shutting it down bypassing the –force flag.

$ docker node rm --force node9
Node node9 removed from swarm

Before we forcefully remove a manager node, we must first demote it to the worker role. 

Make sure that we always have an odd number of manager nodes if we demote or remove a manager.

2. Error response from daemon: rpc error: code = 4 desc = context deadline exceeded

Swarm is resilient to failures and the swarm can recover from any number of temporary node failures or other transient errors. However, a swarm cannot automatically recover if it loses a quorum. Tasks on existing worker nodes continue to run, but administrative tasks are not possible, including scaling or updating services and joining or removing nodes from the swarm. The best way to recover is to bring the missing manager nodes back online.

If we lose the quorum of managers, we cannot administer the swarm. If we have lost the quorum and we attempt to perform any management operation on the swarm, an error occurs:

Error response from daemon: rpc error: code = 4 desc = context deadline exceeded

The best way to recover from losing the quorum is to bring the failed nodes back online. If that is not possible, the only way to recover from this state is to use the –force-new-cluster action from a manager node. This removes all managers except the manager the command was run from. The quorum is achieved because there is now only one manager. Promote nodes to be managers until we have the desired number of managers.

# From the node to recover
docker swarm init --force-new-cluster --advertise-addr node01:2377

When we run the docker swarm init command with the –force-new-cluster flag, the Docker Engine where we run the command becomes the manager node of a single-node swarm that is capable of managing and running services.

The manager has all the previous information about services and tasks, worker nodes are still part of the swarm and services are still running. We need to add or re-add manager nodes to achieve previous task distribution and ensure that we have enough managers to maintain a high availability and prevent losing the quorum.


[Need urgent assistance in fixing Docker errors? – We're available 24*7. ]


This article covers how to install Docker Swarm Cluster on Debian 10. Docker Swarm is a tool used to orchestrate docker hosts. We can create a high availability and a high performance Docker cluster with applications distributed among the hosts. Docker swam uses a manager host and worker nodes architecture. You can have one or several manager nodes in your docker swarm cluster. The manager nodes uses the native Docker API and share the database of the Docker Swarm cluster with the worker nodes. The manager hosts maintain the cluster state, schedule tasks and handle the HTTP API endpoints.