Back up and restore Falak
This page covers backing up Falak itself. Your apps’ databases have their own database backups. For scheduled, off-site backups and recovering a lost host, set up disaster recovery.
Take a backup
Section titled “Take a backup”sudo falak-ctl backupsudo falak-ctl backup --label before-migrationsudo falak-ctl backup --upload # also to the DR bucket (encrypted only)With the DR passphrase set (falak-ctl dr setup), the file is /opt/falak/backups/falak-backup-<UTC timestamp>[-label].fdr, encrypted and authenticated. Without one it is a plain .tar.gz that never leaves the host. It contains:
| Item | Contents |
|---|---|
db.dump |
pg_dump -Fc of the Falak database (including the sealed Fleet CA key and secrets) |
falak-ca |
The Fleet CA certificate and the agent API certificate |
edge-pki |
The edge’s client certificate for the agent API |
app-storage, caddy-data |
Build artifacts and app files; ACME account and certificates |
registry-data |
Only with --include-registry |
env, custom.env |
Your settings and APP_KEY |
secrets/kek |
The KEK — only when the backup is encrypted with the DR passphrase |
manifest |
Falak version, image digests, volumes, KEK id, row counts |
An unencrypted backup warns that it can’t be decrypted without the KEK, and leaves out the KMS / Vault credentials: keep the emergency kit (falak-ctl kek export) apart from your backups.
The newest 14 backups are kept on the host (FALAK_BACKUP_KEEP in .env).
Schedule and encrypt
Section titled “Schedule and encrypt”falak-ctl dr setup stores an S3-compatible bucket and a DR passphrase in /opt/falak/dr/dr.env and installs falak-backup.timer (every 6 hours by default) and a monthly falak-drill.timer. Uploads are always encrypted. See Disaster recovery.
Restore
Section titled “Restore”sudo falak-ctl restore /opt/falak/backups/falak-backup-20261001T030000Z.fdr --yessudo falak-ctl restore falak-backup-20261001T030000Z.fdr --yes # a file in backups/sudo falak-ctl restore s3://latest --yes # the newest upload in the DR bucketsudo falak-ctl restore s3://falak-backup-20261001T030000Z-scheduled --yesThe restore checks the backup’s MAC with the DR passphrase before anything is decrypted, stops the app and edge, restores the database, volumes, .env/custom.env and the KEK, starts the stack, and recreates services whose config files changed. It keeps this host’s version and image settings, and refuses a backup made by a newer Falak (install that version first, or --force).
Move Falak to a new host
Section titled “Move Falak to a new host”- Take an encrypted backup on the old host (
falak-ctl backup --upload), or copy a backup file over. - On the new host, install with the same
--domainand--restore-from s3://latest(see The control plane host is lost), or install and runfalak-ctl restore <file> --yes. Use--skip-dns-checkwhile DNS still points at the old host. - Point DNS for the panel,
agents.,registry.andgrafana.at the new host.
Agents keep working without re-enrolling, because the Fleet CA, the edge PKI and the KEK came with the backup.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Fix |
|---|---|
| Agents go offline after a restore | The database, .env and KEK must come from the same backup (or import the emergency kit). |
| The restore refuses the backup’s KEK | Import the KEK with falak-ctl kek import <kit> --force, then restore again. |
… is not a Falak backup (db.dump/env missing) |
The file is incomplete or not a falak-ctl backup. |
An older *.tar.gz.enc backup |
Restores from a local file only (no MAC, with a warning), never from the bucket. Take a new backup after upgrading. |