Skip to content

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.

Terminal window
sudo falak-ctl backup
sudo falak-ctl backup --label before-migration
sudo 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).

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.

Terminal window
sudo falak-ctl restore /opt/falak/backups/falak-backup-20261001T030000Z.fdr --yes
sudo 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 bucket
sudo falak-ctl restore s3://falak-backup-20261001T030000Z-scheduled --yes

The 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).

  1. Take an encrypted backup on the old host (falak-ctl backup --upload), or copy a backup file over.
  2. On the new host, install with the same --domain and --restore-from s3://latest (see The control plane host is lost), or install and run falak-ctl restore <file> --yes. Use --skip-dns-check while DNS still points at the old host.
  3. Point DNS for the panel, agents., registry. and grafana. at the new host.

Agents keep working without re-enrolling, because the Fleet CA, the edge PKI and the KEK came with the backup.

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.