Coolify Infrastructure

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.

Multi-Server Architecture

How Coolify Multi-Server Works

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)     │
└──────────────────────┘             └──────────────────┘

Adding a Remote Server

1. Prepare the remote server: Install Docker and ensure SSH is configured
2. In Coolify UI: Settings → Servers → Add Server
3. Configure SSH: Provide IP, port, SSH user, and SSH private key
4. Validate: Coolify tests the SSH connection and Docker availability
5. Install Sentinel: Coolify deploys its monitoring agent to the remote server

Requirements for remote servers:

• Docker installed and running
• SSH access from the main Coolify server (key-based auth)
• Ports open: SSH (22), HTTP (80), HTTPS (443) for Traefik on that server
• Coolify installs its own Traefik proxy on each remote server

Deploying the Same App to Multiple Servers

This requires a Docker Registry because:

1. The image is built once (on the build server or main server)
2. The built image is pushed to a registry (GHCR, Docker Hub, private)
3. Each target server pulls the image from the registry
4. Without a registry, the image only exists on the build server

Workflow:

1. Configure a Docker Registry in Coolify (Settings → Docker Registries)
2. Create the application on the main server
3. In Application Settings → set the target server(s)
4. On deploy: Coolify builds → pushes to registry → each server pulls and runs

Load Balancing Across Servers

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):

• Use Cloudflare, AWS ALB, HAProxy, or Nginx as an external LB
• Point the LB to all server IPs running the app
• DNS round-robin is the simplest but least reliable

Option 2: DNS load balancing:

• Add multiple A records for the same domain pointing to different servers
• Simple but no health checking — a dead server still receives traffic

Option 3: Cloudflare Load Balancing:

• Cloudflare's paid LB feature with health checks
• Best option for most Coolify multi-server setups

Docker Swarm (Experimental)

Warning: Docker Swarm support in Coolify is experimental. Not all features work reliably. Use for testing and non-critical workloads only.

Current Status

• Swarm mode can be initialized from the Coolify UI
• Basic service deployment works
• Some Coolify features may not work correctly in Swarm mode
• Community reports mixed results — stability varies by Coolify version

Swarm Setup

1. Minimum servers: 1 manager + 1 worker (3 managers recommended for HA)
2. Architecture: All servers must be the same architecture (amd64 or arm64)
3. Network: All servers must be able to reach each other on ports:

• 2377/tcp (cluster management)
• 7946/tcp+udp (node communication)
• 4789/udp (overlay network)

Initialization

1. In Coolify: Server → Swarm → Initialize as Manager
2. Coolify runs docker swarm init on the main server
3. Add worker nodes: Server → Swarm → Join as Worker
4. Coolify runs docker swarm join --token <TOKEN> on worker servers

Known Limitations in Swarm Mode

When to Use Swarm vs Multi-Server Without Swarm

Build Server Configuration

Separate Build and Deployment Servers

For large or resource-intensive builds, offload the build process to a dedicated server:

1. Add a server in Coolify designated as the build server
2. Configure the application: In Application Settings → Build Server, select the dedicated build server
3. Registry required: The build server pushes the built image to a registry; the deployment server pulls it

Benefits:

• Build process doesn't consume deployment server resources
• Faster builds on a server with more CPU/RAM
• Production server stays responsive during builds

Build Server Requirements

Coolify Instance Management

Backup Strategy

Coolify stores its configuration and state in:

• /data/coolify/ — main data directory
• source/ — Coolify source code and Docker Compose
• databases/ — Coolify's internal PostgreSQL database
• proxy/ — Traefik configuration and ACME certificates
• ssh/ — SSH keys for server management
• applications/ — Application data

Automated 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/ — everything
• Environment: document server OS, Docker version, Coolify version

What NOT to back up (too large, recreatable):

• Docker images (pulled from registry on deploy)
• Build cache (rebuilt on next deploy)

Migration to New Server

1. 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/

1. On new server: Install Coolify fresh

   curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

1. 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 /

1. Start Coolify:

   cd /data/coolify/source
   docker compose up -d

1. Update DNS: Point your Coolify dashboard domain to the new server IP

1. Update remote servers: If remote servers had the old server's SSH key, re-validate connections

1. Verify: Check all applications are running, SSL certificates are valid

Coolify Self-Update

# 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:

• Create a backup of /data/coolify/
• Read the release notes for breaking changes
• Test in staging if running critical production workloads

Anti-Patterns

Related Skills

• coolify-deploy — Deployment configuration, registry patterns
• coolify-security — Server hardening, UFW configuration, SSH security
• coolify-observability — Multi-server monitoring setup
• coolify-databases — Database management on remote servers
• coolify-cicd — Multi-environment CI/CD pipelines

Additional Resources

Reference Files

• `references/multi-server-setup.md` — Step-by-step multi-server configuration with registry
• `references/swarm-guide.md` — Docker Swarm initialization and management in Coolify