Disaster recovery
Keep the secret, database backup, and recovery keys needed to restore Deplo.
Keep these three things
Three things, in order of how badly you want them.
1. DEPLO_SECRET
It lives in /opt/deplo/.env on the panel's host.
Every secret this instance holds derives from it
Every encryption key, session signature, and agent certificate authority is
derived from DEPLO_SECRET. Lose it and every stored secret becomes
unreadable: environment variables, database passwords, S3 keys, registry and
git credentials. Deplo will start, and it will not be able to open anything.
Copy that file into a password manager today. It is five lines on a fresh install, seven once the setup key and the host bootstrap token are appended.
2. The Postgres database
Every app, team, domain, role, token, deployment record, and encrypted secret is a row in it. It runs as a container on the panel's host, on a network that's deliberately not published.
docker compose -f /opt/deplo/docker-compose.yml --env-file /opt/deplo/.env \
exec -T postgres pg_dump -U deplo deplo | gzip > deplo-$(date +%F).sql.gzKeep those dumps somewhere that is not that machine.
3. Backup recovery keys
Every backup destination has one, and it's what decrypts its artifacts. Deplo stores a copy, encrypted with DEPLO_SECRET, which is no help in the scenario where you lost both.
Download each one from the destination's menu and keep them with the secret. With a recovery key, any artifact reads anywhere:
age -d -i recovery-key.txt backup.sql.gz.age > backup.sql.gzYour apps' data
That's what backups are for. Two rules worth stating plainly:
- A backup on the same server as the workload survives everything except losing that server, which is the failure people actually have. Send at least one copy to a bucket or to a backups-only server.
- An app's schedule does not include its databases. Schedule both.
If the control-plane machine is lost
Is the old machine still running?
Then do not restore by hand: use Move Deplo. It needs no shell, never
copies DEPLO_SECRET, and keeps the old Deplo running until you switch. This section is for when
the old machine is gone.
Your apps keep serving. The control plane is not in the request path: Traefik and your containers are on the servers, and they don't need Deplo to keep running. What you lose is deploying, logs, metrics, and the dashboard.
To come back:
Install Deplo on a new machine
curl -fsSL https://deplo.build/install.sh | bashStop it, and restore the secret
Put the old DEPLO_SECRET into /opt/deplo/.env.
Restore the database
Restore the Postgres dump into the new instance's database.
Start it
Migrations apply at boot.
Let the agents reconnect
They pin the old control plane's certificate authority, which was derived from that same secret, so they trust the new one. Where an agent does not reconnect, re-run the agent installer on that host to re-enroll it.
Re-enroll this machine's own server
Its agent enrolled under the fresh install's secret, so it does not trust the
restored one, and re-running install.sh keeps it as it is. It shows under
Settings -> Servers as Provisioning: open it, then Advanced -> Show
install command, and run that command on this machine.
Fix the panel address
Check Settings -> Deplo and set the panel address, then re-point any webhook that names the old address.
Order matters
Secret first, then the database. A restore under the wrong secret produces a working panel full of unreadable secrets.
If an app server is lost
Remove the dead server
That's trust revocation, and it does not need the machine to answer.
If a database refuses to start with a data-copy error after a move, that block is protecting you: an engine started on an emptied volume does not fail, it initializes a brand-new empty database over your data.
Test recovery before you need it
Once, before you need it:
Restore one backup
Into a scratch app or database, and confirm the data is there.
Decrypt one artifact by hand
age -d -i recovery-key.txt backup.sql.gz.age > backup.sql.gzConfirm you can read /opt/deplo/.env
From wherever you filed it.
An untested backup is a hope, not a plan.
Important details
DEPLO_SECRETcannot be rotated. There is no key versioning. Treat it as permanent.- Deplo pushes no images to a registry, so rebuilding an app after losing its server means rebuilding from source. Keep the source somewhere that is not that machine.
- Backup artifacts survive their target's deletion for 30 days, so a deleted-by-mistake app is usually still recoverable. Deleting the schedule alone keeps them indefinitely instead - see backups.
Troubleshooting
A restore fails, a backup won't decrypt, or a database won't start after a move: see Databases and backups troubleshooting.
Next steps
Did this page help you?