Cluster Management Pro

A full Docker Swarm dashboard with node management, service monitoring, cluster visualizer, and secrets/configs management — integrated into Coolify.

Pro Feature

Cluster Management requires a Pro license. Upgrade to unlock.

Overview

Cluster Management provides a Portainer-class experience for Docker Swarm clusters, directly within Coolify. It auto-detects existing Swarm clusters from your servers and provides:

• Cluster dashboard — health, node count, service count, resource usage at a glance
• Node management — drain, activate, promote, demote, add/remove nodes, label management
• Service monitoring — real-time service status, task placement, inline scaling
• Cluster visualizer — visual representation of task placement across nodes
• Events log — filterable stream of Swarm events
• Secrets & configs — create and manage Docker Swarm secrets and configs
• REST API — 21+ endpoints for programmatic cluster management

Enabling Cluster Management

CORELIX_CLUSTER_MANAGEMENT=true

Additional configuration:

Variable	Default	Description
CORELIX_CLUSTER_SYNC_INTERVAL	60	Metadata sync interval (seconds)
CORELIX_CLUSTER_CACHE_TTL	30	Docker API cache TTL (seconds)
CORELIX_CLUSTER_EVENT_RETENTION	7	Event retention (days)

Auto-Detection

When enabled, Cluster Management automatically:

1. Scans your servers for Docker Swarm managers
2. Creates a Cluster entry for each discovered Swarm
3. Links worker nodes by matching IPs to existing Coolify servers
4. Begins periodic metadata synchronization

No manual setup is required if your servers are already in a Swarm.

Navigation

A new Clusters item appears in the sidebar:

• Cluster List — card view of all team clusters with health status
• Cluster Dashboard — tabbed view with Overview, Services, Visualizer, Secrets, Configs, and Events

Each server detail page also shows a link to its cluster (if part of one).

Dashboard

The cluster dashboard provides a comprehensive overview:

• Status cards — cluster health (healthy/degraded/unreachable), node count, service count, task count
• Resource bars — CPU and memory utilization across the cluster
• Node table — all nodes with role, availability, status, and labels

Cluster Health

Status	Meaning
Healthy	All manager nodes reachable, quorum intact
Degraded	Some nodes unreachable, but cluster is operational
Unreachable	Cannot connect to the primary manager

Status transitions trigger notifications through Coolify's notification channels.

Node Management

Node Actions

Action	Description
Drain	Stop scheduling new tasks and migrate existing tasks to other nodes
Activate	Resume task scheduling on a drained node
Promote	Promote a worker to manager role
Demote	Demote a manager to worker role
Remove	Remove a node from the cluster

Adding a Node

The Add Node wizard walks you through:

1. Choose role — manager or worker
2. Copy join command — a pre-generated docker swarm join command with the token
3. Run on new server — paste and run the command on the new node
4. Wait for detection — the node appears in the dashboard automatically

Node Labels

Manage key-value labels on each node for placement constraints:

1. Click a node in the node table
2. Add or remove labels (e.g., env=production, disk=ssd)
3. Use labels in service placement constraints

Service Monitoring

The Services tab shows all Swarm services with:

• Service name, image, and mode (replicated/global)
• Replica count (desired vs running)
• Inline task expansion — click a row to see individual tasks per node
• Task status with color coding (green = running, yellow = pending, red = failed)

Service Operations

Action	Description
Scale	Change replica count inline
Rollback	Revert to the previous service version
Force Update	Trigger a rolling update with no changes (restarts all tasks)

Cluster Visualizer

A visual representation of task placement across your cluster, with two views:

Grid View

Column-per-node layout (Portainer-style):

• Each column represents a node
• Color-coded task blocks: green (running), yellow (pending), red (failed), blue (updating)
• Task blocks show service name and status

Topology View

Interactive node hierarchy:

• Manager and worker relationships displayed visually
• Nodes sized proportionally to their workload
• Connection lines show cluster topology

Secrets & Configs

Secrets

Manage Docker Swarm secrets:

• Create — name and value (value is encrypted by Docker, never readable after creation)
• Rotate — create a new version and update services to use it
• Remove — delete with dependency checking (warns if services reference the secret)

Configs

Manage Docker Swarm configs:

• Create — name and content (plain text, readable after creation)
• View — inspect config content
• Remove — delete with dependency checking

Structured Deployment Config

When cluster management is enabled, Coolify's raw YAML textarea for Swarm applications is replaced with a structured form:

Setting	Options
Mode	Replicated or Global
Replicas	Number of replicas (replicated mode)
Update Policy	Parallelism, delay, failure action, order
Rollback Policy	Parallelism, delay, failure action
Placement Constraints	Visual builder for node constraints
Resource Limits	CPU and memory limits/reservations
Health Check	Command, interval, timeout, retries
Restart Policy	Condition, delay, max attempts, window

API

21+ endpoints for programmatic cluster management:

# List clusters
curl -H "Authorization: Bearer $TOKEN" \
  https://coolify.example.com/api/v1/clusters

# Get cluster details
curl -H "Authorization: Bearer $TOKEN" \
  https://coolify.example.com/api/v1/clusters/{uuid}

# List nodes
curl -H "Authorization: Bearer $TOKEN" \
  https://coolify.example.com/api/v1/clusters/{uuid}/nodes

# Drain a node
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://coolify.example.com/api/v1/clusters/{uuid}/nodes/{id}/drain

# Scale a service
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"replicas": 5}' \
  https://coolify.example.com/api/v1/clusters/{uuid}/services/{id}/scale

# Get visualizer data
curl -H "Authorization: Bearer $TOKEN" \
  https://coolify.example.com/api/v1/clusters/{uuid}/visualizer

# Create a secret
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "db-password", "value": "s3cret"}' \
  https://coolify.example.com/api/v1/clusters/{uuid}/secrets