This skill should be used when configuring multi-server deployments in Coolify, setting up Docker Swarm with Coolify, configuring build servers, managing Coolify instance backups, migrating Coolify to a new server, setting up load balancing across Coolify servers, or managing Coolify infrastructure at scale. Trigger when: "Coolify multi-server", "Coolify multiple servers", "Coolify Swarm", "Docker Swarm Coolify", "Coolify build server", "Coolify backup", "backup Coolify", "migrate Coolify", "Coolify load balancer", "Coolify scale", "Coolify infrastructure", "Coolify high availability", "Coolify instance management".
How this skill is triggered — by the user, by Claude, or both
Slash command
/rad-coolify-orchestrator:coolify-infrastructureThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Covers multi-server deployment, Docker Swarm (experimental), build servers, Coolify instance management, and scaling patterns for Coolify v4 self-hosted.
Covers multi-server deployment, Docker Swarm (experimental), build servers, Coolify instance management, and scaling patterns for Coolify v4 self-hosted.
Stability Warning: Multi-server and Swarm features are evolving. Some configurations may change between Coolify releases. Always test in staging first.
Coolify runs on one main server and can manage additional remote servers via SSH:
┌──────────────────────┐ SSH ┌──────────────────┐
│ Main Coolify Server │────────────►│ Remote Server 1 │
│ (Dashboard + DB + │ │ (Apps + DBs) │
│ Proxy + Apps) │ └──────────────────┘
│ │ SSH ┌──────────────────┐
│ │────────────►│ Remote Server 2 │
│ │ │ (Apps + DBs) │
└──────────────────────┘ └──────────────────┘
Requirements for remote servers:
This requires a Docker Registry because:
Workflow:
Coolify does NOT provide built-in cross-server load balancing. Each server runs its own Traefik instance. To load balance:
Option 1: External load balancer (recommended):
Option 2: DNS load balancing:
Option 3: Cloudflare Load Balancing:
Warning: Docker Swarm support in Coolify is experimental. Not all features work reliably. Use for testing and non-critical workloads only.
docker swarm init on the main serverdocker swarm join --token <TOKEN> on worker servers| Feature | Status |
|---|---|
| Application deployment | Works (basic) |
| Rolling updates | Works (uses Swarm's built-in rolling update) |
| Health checks | Works (Swarm-native) |
| Persistent volumes | Limited (volumes are node-local, not shared) |
| Docker Compose deploy | Partial (converted to Swarm stack) |
| PR preview environments | Not supported |
| Terminal access | Limited |
| Build on deploy | May require registry for multi-node builds |
| Database services | Works on single node; no replication |
| Criteria | Multi-Server (no Swarm) | Docker Swarm |
|---|---|---|
| Complexity | Lower | Higher |
| Load balancing | External LB needed | Swarm built-in routing mesh |
| Service discovery | Container names (same server) | Swarm service names (cross-server) |
| Rolling updates | Coolify-managed | Swarm-native |
| Persistent storage | Volumes per server | Node-local only (need NFS/Ceph for shared) |
| Stability in Coolify | More stable | Experimental |
| Recommendation | Production workloads | Testing/non-critical |
For large or resource-intensive builds, offload the build process to a dedicated server:
Benefits:
| Resource | Recommendation |
|---|---|
| CPU | 4+ cores (builds are CPU-intensive) |
| RAM | 8GB+ (Node.js builds can be memory-hungry) |
| Disk | 50GB+ SSD (Docker build cache is large) |
| Network | Fast connection to Docker Registry |
Coolify stores its configuration and state in:
/data/coolify/ — main data directory
source/ — Coolify source code and Docker Composedatabases/ — Coolify's internal PostgreSQL databaseproxy/ — Traefik configuration and ACME certificatesssh/ — SSH keys for server managementapplications/ — Application dataAutomated backup:
#!/bin/bash
# coolify-backup.sh — Run daily via cron
BACKUP_DIR="/backups/coolify"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="${BACKUP_DIR}/coolify_${TIMESTAMP}.tar.gz"
# Stop Coolify briefly for consistent backup
# NOTE: Running app containers are NOT affected — they continue serving via Traefik
# Only the Coolify dashboard becomes unavailable during this window (~1-2 minutes)
cd /data/coolify/source
docker compose stop
# Create backup
tar -czf "$BACKUP_FILE" /data/coolify/
# Restart Coolify
docker compose up -d
# Upload to S3 (optional)
aws s3 cp "$BACKUP_FILE" s3://<BUCKET>/coolify-backups/
# Retain last 30 backups locally
ls -t ${BACKUP_DIR}/coolify_*.tar.gz | tail -n +31 | xargs rm -f
echo "Backup completed: $BACKUP_FILE"
Cron schedule:
# Daily at 3 AM
0 3 * * * /opt/scripts/coolify-backup.sh >> /var/log/coolify-backup.log 2>&1
What to back up:
/data/coolify/ — everythingWhat NOT to back up (too large, recreatable):
On old server: Stop Coolify and create a backup
cd /data/coolify/source
docker compose stop
tar -czf /tmp/coolify-migration.tar.gz /data/coolify/
On new server: Install Coolify fresh
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
Stop fresh Coolify and restore data:
cd /data/coolify/source
docker compose stop
rm -rf /data/coolify/*
tar -xzf /tmp/coolify-migration.tar.gz -C /
Start Coolify:
cd /data/coolify/source
docker compose up -d
Update DNS: Point your Coolify dashboard domain to the new server IP
Update remote servers: If remote servers had the old server's SSH key, re-validate connections
Verify: Check all applications are running, SSL certificates are valid
# Recommended: Via UI
# Settings → Update → Check for updates → Install
# Via CLI
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
# To pin a specific version (if latest has issues)
# Check available versions at github.com/coollabsio/coolify/releases
Before updating:
/data/coolify/| Anti-Pattern | Consequence |
|---|---|
| Using Swarm for production-critical workloads | Experimental support means unexpected failures |
| No Docker Registry configured for multi-server | Builds fail to propagate to remote servers |
Not backing up /data/coolify/ | Lose all Coolify configuration, SSH keys, and ACME certificates |
| Running builds on the same server as production apps | Build process consumes all CPU/RAM; production apps become unresponsive |
| Using DNS round-robin as the sole load balancing strategy | No health checking; dead servers still receive traffic |
| Exposing Swarm management ports (2377) to the internet | Anyone can join your Swarm cluster |
| Not testing Coolify backups by restoring | Discover corrupt or incomplete backups during an emergency |
| Updating Coolify in production without reading release notes | Breaking changes in database schema or API |
| Running all Coolify infrastructure on a single server | Single point of failure for everything |
| Not securing SSH keys between Coolify main and remote servers | Compromised main server gives access to all remote servers |
references/multi-server-setup.md — Step-by-step multi-server configuration with registryreferences/swarm-guide.md — Docker Swarm initialization and management in Coolifynpx claudepluginhub radorigin-llc/rad-claude-skills --plugin rad-coolify-orchestratorGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.