Back up and restore Falak

This page covers backing up Falak itself. Your apps’ databases have their own database backups.

The Fleet CA is critical

Every agent trusts only Falak’s Fleet CA, and the CA’s private key is stored in the database encrypted with APP_KEY. A backup is only useful with its database and .env together. Lose either and every server must be re-enrolled. Keep copies off the host.

Take a backup

sudo falak-ctl backup
sudo falak-ctl backup --label before-migration

Expected output

==> backup falak-backup-20260928T031500Z
  ✓ database (12M)
  ✓ volumes: falak-ca (Fleet CA), app-storage, caddy-data

The file is /opt/falak/backups/falak-backup-<UTC timestamp>[-label].tar.gz. It contains:

Item	Contents
db.dump	pg_dump -Fc of the Falak database (including the encrypted Fleet CA key)
falak-ca.tar.gz	The Fleet CA certificate and the agent API certificate
app-storage.tar.gz	Build artifacts and app files
caddy-data.tar.gz	ACME account and certificates
env, custom.env	Your settings and secrets (APP_KEY)
manifest	Falak version, time, host, domain

Schedule daily backups

echo '15 3 * * * root /usr/local/bin/falak-ctl backup --quiet' | sudo tee /etc/cron.d/falak-backup

The newest 14 backups are kept (FALAK_BACKUP_KEEP in .env).

Encrypt backups

Set a passphrase in /opt/falak/.env:

FALAK_BACKUP_PASSPHRASE=a-long-random-passphrase

Backups are then written as *.tar.gz.enc (AES-256-CBC, openssl enc -pbkdf2). A restore needs the same passphrase. Store it somewhere other than the host.

Copy backups off the host (S3)

Set these in /opt/falak/.env to upload each backup to an S3-compatible bucket (path-style URLs, curl --aws-sigv4):

Variable	Example / default
FALAK_BACKUP_S3_ENDPOINT	https://s3.eu-central-1.amazonaws.com
FALAK_BACKUP_S3_BUCKET	acme-falak-backups
FALAK_BACKUP_S3_REGION	default us-east-1
FALAK_BACKUP_S3_ACCESS_KEY, FALAK_BACKUP_S3_SECRET_KEY	credentials
FALAK_BACKUP_S3_PREFIX	default falak

The local copy is kept even when an upload fails.

Restore

sudo falak-ctl restore /opt/falak/backups/falak-backup-20260101T030000Z.tar.gz --yes
sudo falak-ctl restore falak-backup-20260101T030000Z.tar.gz --yes          # a file in backups/
sudo falak-ctl restore falak-backup-….tar.gz --yes --keep-env              # keep the current .env

The restore stops the app and edge, restores the database, volumes and .env/custom.env, starts the stack, and recreates services whose config files changed. The falak-ca volume is re-synced by the edge within 3 seconds.

Caution

Use --keep-env only when the current .env has the same APP_KEY as the backup. Otherwise the Fleet CA key cannot be decrypted and agents go offline.

Move Falak to a new host

1. Take a backup on the old host and copy it to the new host.
2. Install Falak on the new host with the same --domain (use --skip-dns-check while DNS still points at the old host).
3. Restore: sudo falak-ctl restore <file> --yes. This brings back the old .env, including APP_KEY.
4. Point DNS for the panel, agents. and grafana. at the new host.

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

Troubleshooting

Symptom	Fix
Agents go offline after a restore	The restored .env/APP_KEY must belong to the same backup as the database.
… is encrypted: set FALAK_BACKUP_PASSPHRASE	Put the passphrase in .env (or the environment) and retry.
… is not a Falak backup (db.dump/env missing)	The file is incomplete or not a falak-ctl backup.

Next steps

UpgradeUpdates take a backup automatically.

SecurityProtect .env and backups.