How to Build a Docker Swarm Cluster with Portainer Visualization on Debian

Environment

Install Docker on Debian 12 hosts: sudo apt install docker.io Host allocation:

OS: Debian 12 (bookworm), Hostname: fs3 (manager), IP: 192.168.1.95, Docker version: v20.10.24

OS: Debian 12 (bookworm), Hostname: fs1 (worker), IP: 192.168.1.91, Docker version: v20.10.24

OS: Debian 12 (bookworm), Hostname: fs0 (worker), IP: 192.168.1.92, Docker version: v20.10.24

Open ports:

2377/tcp – cluster management communication

7946/tcp, 7946/udp – node‑to‑node communication

4789/udp – overlay network

Create Swarm Cluster

2.1 Create manager node

Run on manager node (fs3):

sudo docker swarm init --advertise-addr 192.168.1.95

The command outputs a join token for workers and managers.

2.2 Add worker nodes

Execute on each worker node (fs1, fs0):

sudo docker swarm join --token SWMTKN-1-... 192.168.1.95:2377

To add another manager, use:

sudo docker swarm join-token manager --token SWMTKN-1-... 192.168.1.95:2377

Tokens expire after 24 hours; retrieve a new one with: docker swarm join-token worker Check cluster status with docker info, docker node ls.

2.3 Swarm networks

Swarm creates two default networks:

ingress (overlay) – used for service traffic.

docker_gwbridge (bridge) – connects nodes.

List networks with docker network ls.

Cluster Visualization with Portainer

Deploy Portainer on the manager node for UI management.

3.1 Single‑node deployment

docker pull portainer/portainer-ce:latest
docker run -p 8000:8000 -p 9443:9443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  --name my-portainer -d --privileged=true \
  --restart=always portainer/portainer-ce:latest

3.2 Swarm deployment

Download the stack file:

curl -L https://downloads.portainer.io/ce2-19/portainer-agent-stack.yml -o portainer-agent-stack.yml

Deploy the stack:

docker stack deploy -c portainer-agent-stack.yml portainer

Portainer creates an overlay network agent_network and services portainer_agent and portainer.

3.3 Reset Portainer admin password

docker run --rm -v /var/lib/docker/volumes/portainer_data/_data:/data portainer/helper-reset-password

Deploy a Sample Container Cluster

Pull busybox image and create an attachable overlay network:

docker pull busybox
docker network create -d overlay --attachable busybox_overlay_network

Create a service with two replicas:

docker service create -td --name busybox_service --network busybox_overlay_network --replicas=2 busybox

Load Balancing Stateless Services

Deploy an Nginx service with three replicas and publish port 8080:

docker pull nginx
docker network create -d overlay --attachable nginx_overlay_network
docker service create -td --name nginx_service --network nginx_overlay_network --replicas=3 -p 8080:80 nginx

Verify load balancing by customizing the index.html on each node and accessing the service.