Restore Coolify
Restoring Coolify replaces the instance database with a backup. It restores your projects, resources, settings, saved credentials, and deployment history.
It does not restore data stored inside your applications, databases, services, or volumes.
The Coolify team manages Coolify Cloud instance recovery. This guide is for self-hosted Coolify instances.
Before you restore
Make sure you have:
- a Coolify database backup file ending in
.dmp - the value after
APP_KEY=in/data/coolify/source/.envthat you saved when you followed Back up Coolify - SSH access to the server where you will restore Coolify
- the version number shown in the Coolify dashboard when the backup was created, if you saved it
- when moving Coolify to another machine, access to
/data/coolify/ssh/keys/and~/.ssh/authorized_keyson the original machine, or a separate backup of those files
If the backup is in S3, download it from your S3 storage provider and copy it to the server where you will perform the restore.
The restore command removes the current Coolify database objects before loading the backup. Do not continue unless the backup file and saved APP_KEY belong to the instance you want to recover.
Prepare the restore target
Choose where you are restoring Coolify.
Choose this option when you are restoring Coolify on the same machine where the instance was already installed.
Confirm that the coolify-db container is running, then place the backup somewhere on that machine, such as /data/backups/coolify-db-backup.dmp.
docker ps --filter name=coolify-db --format '{{.Names}} {{.Status}}'The command should show coolify-db as running and healthy.
Restore the instance
Check the backup file
Confirm that the backup exists and is not empty:
export BACKUP_PATH=/data/backups/coolify-db-backup.dmp
test -s "$BACKUP_PATH" && ls -lh "$BACKUP_PATH"Change the value of BACKUP_PATH if your backup is stored somewhere else. The restore command below uses this variable, so you only need to enter the file path once.
Stop the Coolify control plane
Stop the containers that can use the instance database, but keep coolify-db running:
docker stop coolify coolify-redis coolify-realtimeThe dashboard will be unavailable during the restore. Deployed resources and Coolify Proxy keep running.
Set the saved APP_KEY
Coolify needs the same APP_KEY value that was used when the database backup was created. Without it, Coolify cannot read encrypted credentials and private keys from the restored database.
Open Coolify's environment file on the server where you are performing the restore:
sudo nano /data/coolify/source/.envFind the APP_KEY= line and replace its current value with the APP_KEY value you saved while following Back up Coolify.
If you are restoring Coolify on the original machine and the existing value already matches the saved value, leave the APP_KEY= line unchanged.
On a replacement server, keep the rest of the new installation's .env file. Values such as DB_PASSWORD belong to the new installation and must continue to match its running containers.
Restore the database
Run the restore while coolify-db is the only Coolify container using the database:
docker exec -i coolify-db pg_restore \
--clean \
--if-exists \
--exit-on-error \
--no-acl \
--no-owner \
--username=coolify \
--dbname=coolify \
< "$BACKUP_PATH"--exit-on-error stops the restore at the first error so a failed restore is not mistaken for success.
Restore the SSH keys
If the original key files are still under /data/coolify/ssh/keys/, skip this step.
If those files were removed, restore them from a separate backup before continuing.
Start Coolify
Run the installer again. If you installed a specific Coolify version, include that version number:
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash -s 4.1.24.1.2 is an example. Replace it with the version you installed before restoring the database. If you installed the latest stable release, omit -s 4.1.2.
The installer starts the Coolify containers and applies any required database migrations.
Wait for the installation to finish before opening the dashboard.
Verify the restore
Open the Coolify dashboard after the installer finishes.
Confirm that:
- the dashboard opens without an encryption error
- your projects, environments, and resources are present
- Servers > localhost validates successfully
- other managed servers connect successfully
- recent deployments and instance settings appear as expected
Application volume and database data are not part of an instance backup. Restore those resources from their own backups when needed.