Coolify Migration Tool

Migrate your Coolify installation between servers with minimal hassle. Two scripts, one manual step.

Features

• ✅ Complete backup - Coolify config, database, SSH keys, environment files
• ✅ All Docker volumes - Your app data, databases, everything
• ✅ Network configurations - Preserves your Docker networks
• ✅ Version detection - Automatically detects and restores the same Coolify version
• ✅ Simple HTTP transfer - No manual file copying needed
• ✅ Universal - Works with any Coolify installation

Quick Start

On your OLD server (DigitalOcean, etc.)

curl -fsSL https://raw.githubusercontent.com/erenbertr/coolify.migrate/main/transfer.sh -o transfer.sh
chmod +x transfer.sh
sudo ./transfer.sh

This will:

1. Stop Coolify temporarily
2. Backup everything
3. Restart Coolify
4. Serve the backup via HTTP
5. Display the download URL

On your NEW server (Hetzner, etc.)

curl -fsSL https://raw.githubusercontent.com/erenbertr/coolify.migrate/main/restore.sh -o restore.sh
chmod +x restore.sh
sudo ./restore.sh

When prompted, enter the URL from the transfer script output.

⚠️ Required: Fix SSH Connection (After Restore)

After restore completes, your localhost server will show "not reachable". This is expected - you need to add the SSH key:

1. Open Coolify at http://YOUR_NEW_SERVER_IP:8000
2. Go to Security → Private Keys → localhost's key
3. Copy the Public Key shown there
4. On your server, run:

   echo "PASTE_THE_PUBLIC_KEY_HERE" >> /root/.ssh/authorized_keys

5. Go to Servers → localhost → Click Validate Server

Now your server should show as connected and you can redeploy your applications.

What Gets Transferred

Component	Location	Included
Coolify Config	/data/coolify/	✅
Database (SQLite/PostgreSQL)	Docker volume coolify-db	✅
SSH Keys	/data/coolify/ssh/	✅
Environment Files	/data/coolify/source/.env	✅
Applications Data	/data/coolify/applications/	✅
Databases Data	/data/coolify/databases/	✅
Docker Volumes	All Coolify-managed volumes	✅
Docker Networks	Coolify networks	✅

Requirements

Source Server

• Root access
• Coolify installed at /data/coolify
• Docker running
• curl or wget

Destination Server

• Root access
• Fresh Ubuntu 22.04/24.04 (recommended)
• Internet access
• curl or wget

Docker will be installed automatically if not present.

Configuration

Custom Port

The transfer script serves backups on port 9999 by default. To use a different port:

SERVE_PORT=8888 sudo ./transfer.sh

Manual Transfer

If HTTP serving doesn't work (firewall issues), you can manually transfer:

# On new server
scp root@OLD_SERVER_IP:/tmp/coolify-migration/coolify-backup-*.tar.gz /tmp/

# Then run restore with local file
sudo ./restore.sh file:///tmp/coolify-backup-XXXXX.tar.gz

Post-Migration Checklist

After running restore.sh:

1. ⚠️ Fix SSH Connection (see instructions above) - Required!
2. Update DNS - Point your domains to the new server IP
3. Redeploy Applications - After SSH is fixed, redeploy your apps
4. Verify SSL - Certificates should auto-renew after redeploy
5. Update Webhooks - GitHub/GitLab webhook URLs
6. Shutdown Old Server - Only after everything is verified

Why SSH Requires Manual Step

Coolify stores the localhost SSH private key in its database and regenerates the key files on every container start. The private key from the old server won't work on the new server because:

1. The key is tied to the old server's authorized_keys
2. Coolify overwrites /data/coolify/ssh/keys/ on startup

The simplest solution is to copy the public key from Coolify UI and add it to authorized_keys on the new server.

Troubleshooting

Coolify won't start

cd /data/coolify/source
docker compose -f docker-compose.yml -f docker-compose.prod.yml logs -f

Note: Coolify uses TWO compose files. Always use both:

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Server shows "not reachable"

Follow the SSH key instructions above. This is the most common issue after migration.

Port 9999 blocked

Either use a different port or transfer manually via SCP.

Database errors (tables don't exist)

The coolify-db volume wasn't restored properly. Fix manually:

# Stop Coolify
cd /data/coolify/source
docker compose -f docker-compose.yml -f docker-compose.prod.yml down

# Remove and restore the database volume
docker volume rm coolify-db
docker volume create coolify-db
docker run --rm \
  -v coolify-db:/target \
  -v /tmp/coolify-restore/coolify-backup-*/docker-volumes/coolify-db.tar.gz:/backup.tar.gz:ro \
  alpine sh -c "cd /target && tar -xzf /backup.tar.gz"

# Start Coolify
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Builds stuck or failing

Coolify needs a buildx builder. Create it manually:

docker buildx create --name coolify --driver docker-container --bootstrap

Also pull required images:

docker pull ghcr.io/coollabsio/coolify-helper:latest
docker pull ghcr.io/railwayapp/nixpacks:latest
docker pull node:18-alpine
docker pull node:20-alpine

If builds are still stuck, clear the build cache:

docker builder prune -af

npm install hangs during build

This can happen with old package-lock.json files. Options:

1. In your repo: Delete package-lock.json, run npm install locally, commit the new lockfile
2. In Coolify: Change build command to: rm -f package-lock.json && npm install && npm run build
3. Check network: Verify npm registry is accessible:

   docker run --rm node:20-alpine npm ping

Volumes not restored

Check if volumes exist and have data:

docker volume ls | grep coolify
docker run --rm -v coolify-db:/data alpine ls -la /data/

Applications show "Exited" but services work

After fixing SSH, you need to redeploy your applications. The containers from the old server won't automatically start - Coolify needs to rebuild them on the new server.

Known Issues & Limitations

1. SSH keys require manual setup - Coolify stores keys in its database and regenerates files on startup. You must add the public key to authorized_keys manually after migration.

2. First deploys may be slow - Docker needs to pull base images and rebuild caches on the new server.

3. Webhooks need updating - GitHub/GitLab webhooks still point to the old server IP.

4. SSL certificates - Will be regenerated automatically on first deploy, but may take a few minutes.

How It Works

transfer.sh

1. Detects Coolify version and configuration
2. Stops Coolify for consistent backup
3. Creates tarball of /data/coolify
4. Exports all Docker volumes (including coolify-db)
5. Saves network configurations
6. Creates metadata file with version info
7. Restarts Coolify
8. Serves backup via Python HTTP server

restore.sh

1. Installs Docker if needed
2. Downloads and extracts backup
3. Validates backup integrity
4. Stops existing Coolify and removes old volumes
5. Restores /data/coolify
6. Recreates and restores Docker volumes with data
7. Recreates Docker networks
8. Updates server IP in configuration
9. Creates Docker Buildx builder for app builds
10. Prepares SSH configuration
11. Starts Coolify
12. Shows instructions for SSH key setup

Security Notes

• The HTTP server runs temporarily for file transfer
• Backup contains sensitive data (SSH keys, database)
• Delete the backup file after successful migration
• The served file is only accessible while the script runs

License

MIT License - Use freely, no warranty.

Contributing

PRs welcome! Please test on a non-production server first.

---

Made with ❤️ for the Coolify community