Disaster recovery
What to keep so losing a machine is a bad afternoon, not the end, and the order to restore things in.
What actually matters
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's four lines.
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.
Losing the panel's machine
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.
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.
Losing an app server
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.
A ten-minute drill worth doing
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.
Limits and gotchas
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.
If it does not work
If it does not work
A restore fails, a backup won't decrypt, or a database won't start after a move: see Databases and backups troubleshooting.
See also
Did this page help you?