iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Antihost offers VPS plans with one-click Coolify, NVMe storage and a 14-day free trial.
A safe Coolify migration has two separate jobs: restore the Coolify control plane, then restore the applications and their data. Create and verify an instance backup, save the original APP_KEY and Coolify SSH keys, install the same Coolify release on a fresh Linux server, restore the control-plane PostgreSQL dump, move databases and files with workload-specific backups, test on a temporary domain, and only then change production DNS.
Understand what you are moving
Coolify is the control plane: it stores projects, resources, settings, credentials, deployment history, and the instructions used to manage servers. Docker on the connected machines is the workload layer: it runs your applications, databases, caches, queues, and other services. A migration can move one layer or both, and the safest plan starts by deciding which one is changing.
- Control-plane move: the Coolify dashboard and its PostgreSQL database move to a replacement server, while workloads remain on their existing machines.
- Workload-server move: applications and services move to another Docker host, while the existing Coolify control plane continues to coordinate them.
- Whole-instance move: both the Coolify control plane and the workload state move. This requires the most coordination and a final write freeze.
Coolify’s instance backup is not a complete server image. It restores the control-plane database, not data inside application containers, databases, Docker volumes, bind mounts, or other services.
| Data or setting | Restored by a Coolify instance backup? | What to do |
|---|---|---|
| Projects and resources | Yes | Restore the instance database. |
| Coolify settings and saved credentials | Yes, when the original APP_KEY is retained |
Restore the key before opening the restored dashboard. |
| Deployment history | Yes | Included in the control-plane database. |
| Application databases | No | Use a logical backup from each database engine and restore it separately. |
| Docker volumes and bind-mounted files | No | Archive or copy them separately, preserving ownership and permissions. |
| Service data and files outside Coolify’s database | No | Inventory and back up each workload’s persistent state. |
Choose a migration strategy
A whole-instance restore is usually the quickest way to reproduce a mature Coolify setup. An application-by-application move gives you a cleaner redesign and lets you leave unused resources behind, but it requires more manual configuration and testing.
#1 Best Overall
| Decision point | Whole-instance restore | Application-by-application move |
|---|---|---|
| Scope | All control-plane projects, resources, settings, credentials, and history | Only the applications and configuration you select |
| State handling | One Coolify database restore plus separate workload backups | Separate Coolify resources, database dumps, volume archives, and file copies |
| Downtime | Requires a final write freeze for databases and files | Can be staged per application, but each application still needs a consistent final copy |
| Secrets and access | Requires the original APP_KEY, Coolify SSH keys, provider tokens, and authorized keys |
Requires recreating or transferring access for every selected resource |
| Rollback | Keep the old instance unchanged and return DNS if needed | Rollback is handled per application and can be more complicated |
| Best fit | Replacing a failed, undersized, or obsolete Coolify server | Reducing clutter, changing architecture, or moving only a subset of projects |
Prepare before changing the source server
Do the preparation while the original environment is healthy. A migration is much easier to recover when the source remains available and untouched until the destination has passed production tests.
- Record whether you are moving the control plane, workload servers, or both.
- Inventory every project, application, database, service, persistent volume, bind mount, scheduled task, webhook, registry, and external integration.
- Confirm SSH access to the replacement machine and enough CPU, memory, disk, and network capacity for the workloads you intend to run.
- Choose an off-server location for the Coolify backup, such as S3-compatible storage, and verify that you can download from it.
- Plan a temporary hostname or alternate DNS record for validation before production traffic moves.
- Reserve a maintenance window for the final database dump and file copy. Applications that accept writes must be stopped or placed in a read-only mode long enough to obtain a consistent final state.
Step-by-step migration runbook
1. Create and verify the Coolify instance backup
In the original Coolify dashboard, open Settings > Backup, configure the destination, and run a backup. Confirm that the execution completed successfully and that the resulting .dmp file is accessible from outside the source server. A backup that merely appears in the dashboard but cannot be downloaded is not a usable migration copy.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsAlso save the complete APP_KEY= line from /data/coolify/source/.env. Store it in a password manager or another protected location. The key encrypts values such as saved credentials; without the original key, the restored database may be present but Coolify cannot read its encrypted secrets.
2. Back up application databases and files separately
For every database running in a workload, use that database engine’s logical backup procedure. A logical dump is portable and consistent at the SQL level; it is not the same as copying a live database container’s volume. Do not use a raw copy of a running database’s Docker volume as a substitute for a database-aware backup.
List every Docker volume and bind-mounted directory used by applications and services. Archive or copy those paths while retaining ownership, group, mode bits, symbolic links, and timestamps where the application depends on them. Include uploads, media, certificates kept in a mounted directory, queue data, search indexes that cannot be regenerated, and any host files referenced by a compose definition.
Keep the workload backups independent of the Coolify .dmp. Restoring the control-plane database does not recreate application rows, user uploads, or service state.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
3. Build the replacement server
Use a fresh Linux VPS or server with reliable SSH access. Coolify can provision supported providers, or you can add an existing Linux machine manually. Size the destination for the real workload, not merely for the Coolify dashboard: account for database memory, image layers, build space, volume growth, backups, and temporary space needed during restores.
When Coolify validates or provisions a server, it may install or verify Docker and Docker Compose and can restart Docker. Existing containers on that machine may therefore be unavailable briefly. Do not point production traffic at a host that still contains unrelated services until you have accounted for that interruption.
4. Install a compatible Coolify release
Install Coolify on the replacement machine. For a restore, use the release shown when the backup was created whenever that information is available. If the installer supports a version argument, rerun it with that version rather than restoring into an arbitrary newer release. After the database is restored and the containers restart, apply upgrades deliberately instead of combining an untested version change with the migration.
5. Transfer and check the .dmp file
Download the backup from its remote storage provider and copy it to the replacement server over a protected channel. Before running PostgreSQL, check that the path is correct and that the file is non-empty. A truncated or zero-byte dump can replace a healthy control-plane database with an unusable one.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchls -lh /path/to/coolify-backup.dmpKeep the original remote copy until the new instance has passed validation. If you have multiple backup dates, label the chosen file clearly and record its creation time.
6. Preserve the encryption key and target-only settings
On the new installation, keep environment values generated for that installation, including its database password. Replace only the target APP_KEY with the exact value saved from the source. Do not copy the entire source environment file over the new one: it can overwrite target database credentials, host-specific paths, or other values that must remain local to the replacement.
After editing the environment, verify that the line is syntactically intact, has no accidental whitespace, and is available to the Coolify containers when they restart.
7. Restore the Coolify control-plane database
Leave coolify-db running so PostgreSQL can accept the restore. Stop coolify and coolify-redis; on older releases, stop coolify-realtime as well. Restoring while the application is writing to the database can create conflicts or leave the restored state inconsistent.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Rank #3
- Upgraded Two Zipper Pockets: Forvencer server books feature two secure zipper pockets for better organization of coins, cash, and receipts, ensuring that everything you collect has a safe and secure place
- Smart Storage & Quick Access: Designed with 8 multi-functional compartments, the right side includes a guest receipt pad, while the left has a money pocket, ticket pocket, and credit card slot. Two small clear pockets store bills, receipts, and other visible items. A stitched pen loop ensures you always have your favorite pen ready
- High-quality & Easy to Clean: Crafted from high-quality PU leather with heavy-duty stitching, this server book is built to last. It resists tears, scratches, and its waterproof surface makes cleaning easy with just a damp cloth or a non-chlorine sanitizer
- Perfect Fit for Your Apron: Measuring 5” x 8”, this compact organizer is slightly smaller than other models, making it ideal for bending or sitting while carrying in your server apron. It holds everything a waitress needs—a place for everything
- What's Included: This server organizer comes with multiple open and zippered pockets to store money, receipts, tips, etc. Clear sleeves are perfect for keeping menus or special lists while serving. Available in a variety of colors, allowing you to express yourself even when in uniform
Run the documented restore command, replacing the final path with the dump you transferred:
docker exec -i coolify-db pg_restore --clean --if-exists --exit-on-error --no-acl --no-owner --username=coolify --dbname=coolify < /path/to/coolify-backup.dmpThe --clean and --if-exists options remove objects that conflict with the dump; --exit-on-error stops at the first restore error; and --no-acl --no-owner avoids applying source ownership and access-control metadata that may not exist on the new server. Read the command output. A command that returns to a prompt is not proof that every object restored if warnings or errors were printed.
8. Restore Coolify’s SSH keys
Copy the original Coolify SSH key files into /data/coolify/ssh/keys/ on the replacement server, and restore the relevant authorized_keys files from the original or a separate secure backup. These keys are distinct from the APP_KEY: the former authenticate server connections, while the latter decrypts Coolify’s stored secrets.
Set ownership and permissions to match the new installation’s expectations. Avoid placing private keys in a world-readable directory or pasting them into shell history.
9. Restart the installation and apply migrations
Rerun the Coolify installer as directed for the selected release so the containers start and any required migrations are applied. Wait for the dashboard and its dependent services to become healthy before beginning application restoration. If the dashboard reports encryption errors, stop and recheck the original APP_KEY rather than generating a new one.
10. Validate the restored control plane
Use a private browser window or a temporary hostname and work through the dashboard systematically:
- Sign in and confirm that no encryption or unreadable-secret error appears.
- Check that projects, resources, instance settings, saved credentials, and deployment history are present.
- Run localhost or built-in server validation and resolve any Docker, disk, or permission error it reports.
- Confirm that each managed server is reachable over SSH with the restored keys.
- Open a resource’s deployment configuration and verify that domains, repositories, registries, environment variables, and schedules point to the intended destinations.
- Check that the replacement server’s storage paths and network addresses match what the workloads expect.
Do not interpret a successful dashboard login as proof that application data has moved. The control plane can be healthy while every database volume is still empty.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →11. Restore workload databases and persistent files
Restore each logical database dump into the matching database service, using the service’s documented restore method and credentials. Recreate users, extensions, collations, and privileges required by the application if they are not contained in the logical dump. Then restore Docker volumes and bind-mounted directories to the paths referenced by the application definitions.
Start one application at a time. Inspect container logs, run its health check, and verify that it can read and write the restored data. For stateful services, allow indexes, migrations, or replay operations to finish before testing dependent applications.
12. Test with a temporary domain before cutover
Point a temporary hostname at the destination and test the complete request path. Check TLS issuance or certificate installation, redirects, uploads, background jobs, queues, webhooks, outbound email, registry pulls, scheduled tasks, and any callback URL that depends on the public hostname. Trigger a test deployment and at least one scheduled or background operation.
Keep production DNS unchanged while these tests run. This gives you a clear rollback route and prevents users from writing to two independent copies of a database.
Free tools Windows power users keep installed
One-click scans. No signup required.
13. Perform the final freeze and DNS cutover
When the destination passes testing, stop application writes on the source. Take a final logical dump of every changing database and a final copy of changing files and volumes. Restore those final copies on the destination, check application health again, and then update DNS and TLS records.
After DNS propagation begins, update integrations that contain the old address or hostname: webhooks, CI/CD secrets, registry credentials, monitoring checks, scheduled-task endpoints, OAuth or callback URLs, and external allowlists. Trigger a deployment and a background operation after the change so failures are found while the source is still available.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Rollback without making the split-brain problem worse
Keep the source server unchanged until the destination is stable for the retention period you have chosen. If rollback is required, stop writes on the destination, record or preserve any destination changes you may need, return DNS to the source, and verify critical flows there.
DNS rollback changes where new requests go; it does not merge databases. Any writes accepted by the destination after cutover must be reconciled manually before they can safely appear on the source. The longer both environments accept writes, the harder recovery becomes.
Common failure modes and fixes
The dashboard opens but saved credentials cannot be used
The replacement likely has a different APP_KEY or the value was altered while copying the environment. Stop and restore the exact source key, then restart the Coolify containers. Do not create a new key if you need the encrypted values from the backup.
The restore command reports missing or conflicting objects
Confirm that coolify-db is running, that coolify and Redis are stopped, and that the dump belongs to the intended Coolify release. Check the file size and read the first error printed by pg_restore. Repeating the command without correcting the first error can leave a partial restore.
Projects are visible but applications have no data
This is expected when only the Coolify instance backup was restored. Restore the application databases, Docker volumes, and bind-mounted files separately, then verify ownership and mount paths.
Managed servers show as unreachable
Check that the original Coolify SSH keys and the required authorized_keys entries were restored, that the destination can reach the server over SSH, and that firewall rules allow the connection. A changed host address may also require updating the server definition in Coolify.
Recommended Free Tools
Applications fail after DNS changes
Use the temporary-domain test results to isolate the issue. Common causes include certificates still covering only the old hostname, webhooks and callbacks retaining the old URL, missing registry credentials, or an application pointing at an old database address. Correct one dependency at a time and repeat the health check.
The old server was deleted too soon
Deleting a provider machine or Coolify resource can permanently destroy application files, databases, volumes, and backups. If the source is still available, stop further changes and use it as the rollback reference. If it has been deleted, recovery depends on independent database, file, and remote-backup copies.
Final migration checklist
- Control-plane and workload scope is documented.
- Coolify backup completed and was downloaded or independently verified.
- Original
APP_KEYis stored securely and restored exactly. - Every application database has a logical backup.
- Volumes and bind-mounted directories were copied with permissions intact.
- Replacement Linux capacity, SSH access, Docker, and storage were validated.
- Coolify was installed at a compatible release.
- The control-plane dump restored without unreviewed errors.
- Coolify SSH keys and authorized keys were restored securely.
- Projects, resources, secrets, history, managed servers, and settings were checked.
- Workload databases and files were restored and tested.
- Temporary-domain tests covered TLS, deployments, uploads, jobs, webhooks, monitoring, and callbacks.
- Final writes were frozen before the last dump and file copy.
- DNS, TLS, automation, credentials, and scheduled operations were updated.
- The source remains intact until the retention and rollback period ends.
How much does the replacement infrastructure cost?
Costs depend on the destination’s CPU, memory, storage, region, backups, and workload density. One documented figure is that backups for a Hetzner server add 20% to the monthly server price; treat that as the provider’s stated surcharge at the time of the Coolify documentation, not as a universal migration cost. Remote S3-compatible storage, extra disk for parallel copies, and temporary overlap between source and destination can also affect the total.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
