Distribute Workloads with Docker Swarm Clustering in Dokploy

Docker Swarm lets you spread your containerised workloads across multiple physical or virtual machines, providing horizontal scaling and high availability without the operational complexity of Kubernetes. Dokploy integrates with Docker Swarm natively — you can add and remove nodes, inspect cluster state, and view per-node application placement, all from the Dokploy dashboard.

What is Docker Swarm?

Docker Swarm is the built-in clustering and orchestration mode in Docker Engine. A Swarm consists of one or more manager nodes (which schedule services and maintain cluster state) and any number of worker nodes (which execute container workloads). Unlike Kubernetes, Swarm requires no additional software: if Docker is installed, Swarm is available. Key concepts:

Concept	Description
Node	A host participating in the Swarm
Manager node	Coordinates the cluster, stores Raft state, and schedules services
Worker node	Runs containers assigned by managers
Service	A long-running containerised workload with a configurable replica count
Task	A single container instance that is part of a service

Dokploy Swarm Integration

Dokploy exposes Swarm management through two routers:

cluster – handles joining and leaving the Swarm (worker/manager join tokens, node removal)
swarm – queries cluster state (node list, node info, per-node applications, container stats)

Both routers communicate with Docker either locally or remotely via the registered serverId, using getRemoteDocker under the hood.

Initializing a Swarm

Swarm mode must be initialised on your primary (manager) node before adding other nodes. In the Dokploy dashboard:

Navigate to Swarm (or Cluster) in the sidebar.
If no Swarm is active, click Initialize Swarm.
Dokploy calls Docker’s swarm init API on the target server.

Once initialised, the manager node is ready to accept join requests from workers and additional managers.

The following network ports must be open between all Swarm nodes for the cluster to operate correctly:

Port	Protocol	Purpose
`2377`	TCP	Swarm management traffic
`7946`	TCP & UDP	Node-to-node communication
`4789`	UDP	Overlay network (VXLAN) data plane

Open these ports in your cloud security group or ufw rules before adding nodes.

Adding Nodes

Add a Worker Node
Add a Manager Node
Remove a Worker Node

Retrieve the worker join token from the Dokploy UI (or API via cluster.addWorker). The endpoint inspects the Swarm, extracts JoinTokens.Worker, and returns the complete join command:

docker swarm join --token SWMTKN-1-<worker-token> <manager-ip>:2377

Run this command on the machine you want to add as a worker. The manager IP is resolved automatically from the Swarm’s NodeAddr or the server’s registered ipAddress.Steps in the dashboard:

Go to Swarm → Nodes → Add Worker.
Copy the displayed docker swarm join command.
SSH into the prospective worker node and run the command.
Refresh the nodes list to confirm the new node appears with Ready status.

Use cluster.addManager to retrieve the manager join token (JoinTokens.Manager). The returned command is identical in structure to the worker command but uses the manager token:

docker swarm join --token SWMTKN-1-<manager-token> <manager-ip>:2377

Run this on the host you want to promote to manager.

Docker Swarm requires a quorum of managers to maintain cluster availability. With an even number of managers, you risk a split-brain scenario. Use an odd number of manager nodes (1, 3, 5…). A 3-manager cluster can tolerate one manager failure; a 5-manager cluster can tolerate two.

To drain and remove a worker node, use cluster.removeWorker and supply the nodeId. Dokploy runs two commands on the manager:

# 1. Drain the node so no new tasks are scheduled on it
docker node update --availability drain <nodeId>

# 2. Forcefully remove the node from the cluster
docker node rm <nodeId> --force

In the dashboard: navigate to Swarm → Nodes, click the node you want to remove, and select Remove Node. The operation is audited automatically.

Viewing Cluster State

List all nodes

cluster.getNodes (or swarm.getNodes) returns the full Docker node list as returned by docker.listNodes() / getSwarmNodes(). Each node entry includes:

ID – unique node identifier
Description.Hostname – node hostname
Spec.Role – manager or worker
Spec.Availability – active, pause, or drain
Status.State – ready or down
ManagerStatus – present on manager nodes, includes leader flag and reachability

Inspect a single node

swarm.getNodeInfo takes a nodeId (and an optional serverId for remote clusters) and returns detailed information about a specific node, including resource reservations, engine version, and platform details.

Deploying Replicated Services

When you deploy an application in Dokploy with Swarm mode active, the container runs as a Docker service rather than a standalone container. This enables:

Replica scaling – set the number of task replicas in the application settings. Swarm automatically distributes replicas across available worker nodes.
Rolling updates – Swarm replaces tasks one by one during redeployments, keeping the service available throughout.
Self-healing – if a task crashes or a node goes down, Swarm reschedules the task on a healthy node.

Example service deployment with 3 replicas:

# Docker Compose / Swarm stack definition
services:
  web:
    image: my-app:latest
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 10s
      restart_policy:
        condition: on-failure

Use placement constraints to pin services to specific nodes (e.g., nodes with GPU resources or specific labels):

deploy:
  placement:
    constraints:
      - node.role == worker
      - node.labels.region == eu-west

Viewing Node Applications

swarm.getNodeApps calls getNodeApplications on the backend, which queries the Docker API to map running service tasks back to the node they are executing on. This gives you a per-node view of what is currently running — useful for diagnosing placement issues or load imbalance across the cluster. swarm.getAppInfos accepts an array of application names and returns detailed service info for each via getApplicationInfo. For real-time container resource consumption across the entire cluster, use swarm.getContainerStats, which calls getAllContainerStats and returns CPU, memory, and network stats for every running container.

Swarm vs Single-Node

Use Single-Node when…

You have a single VPS or development machine
Your workloads don’t need horizontal scaling
You want the simplest possible setup with no distributed-system overhead
Your application handles high availability at the code level (e.g., stateless with a managed DB)

Use Docker Swarm when…

You need to run multiple replicas across several hosts for fault tolerance
You want zero-downtime rolling deployments out of the box
Your traffic spikes require horizontal scaling
You need to isolate workloads across nodes (e.g., separate GPU nodes)

Get Started

Core Features

Infrastructure

Integrations

Administration

Enterprise

Distribute Workloads with Docker Swarm Clustering in Dokploy

What is Docker Swarm?

Dokploy Swarm Integration

Initializing a Swarm

Adding Nodes

Viewing Cluster State

List all nodes

Inspect a single node

Deploying Replicated Services

Viewing Node Applications

Swarm vs Single-Node

Use Single-Node when…

Use Docker Swarm when…

Build docs developers (and LLMs) love

Get Started

Core Features

Infrastructure

Integrations

Administration

Enterprise

Documentation Index

​What is Docker Swarm?

​Dokploy Swarm Integration

​Initializing a Swarm

​Adding Nodes

​Viewing Cluster State

​List all nodes

​Inspect a single node

​Deploying Replicated Services

​Viewing Node Applications

​Swarm vs Single-Node

Use Single-Node when…

Use Docker Swarm when…

Build docs developers (and LLMs) love

What is Docker Swarm?

Dokploy Swarm Integration

Initializing a Swarm

Adding Nodes

Viewing Cluster State

List all nodes

Inspect a single node

Deploying Replicated Services

Viewing Node Applications

Swarm vs Single-Node