Upgrading to v0.10.0
v0.10.0 is a breaking release. Nobody ran Falak in production before it, so it carries no compatibility shims: host databases are no longer managed, secrets move to a new key hierarchy, and agents must match the control plane’s version. Read this page before you run falak-ctl update.
Before you start
Section titled “Before you start”- Back up every database you need that Falak manages on your servers: a dump of each, kept outside Falak. Earlier versions installed PostgreSQL, MySQL, MariaDB, Redis and Valkey on the hosts; v0.10.0 forgets them (see Databases).
- Back up Falak itself:
sudo falak-ctl backup(the update takes one too). - Keep
APP_KEYunchanged until the update has finished.
Update the control plane
Section titled “Update the control plane”The KEK file must exist before v0.10.0 starts, and the falak-ctl that runs an update is the one already installed. So install the v0.10.0 falak-ctl first; it creates the KEK during the update:
curl -fsSL https://github.com/falak-sh/falak/releases/download/v0.10.0/falak-ctl -o /usr/local/bin/falak-ctlchmod 755 /usr/local/bin/falak-ctlfalak-ctl update --version v0.10.0falak-ctl kek export /root/falak-emergency-kit.txt # then store it offline and delete it hereDuring the update a migration re-encrypts every secret once: it decrypts each value with APP_KEY and seals it under a new data key, wrapped by the key-encryption key. Values already converted are skipped, so an interrupted migration can run again. There is no fallback afterwards. Export the emergency kit right away, as above.
If you update with an older falak-ctl, the containers refuse to start without the KEK and the update rolls back. That run has already installed the new falak-ctl, so falak-ctl update again then works. Backups taken before v0.10.0 restore as before: the migration converts them again.
Databases move into containers
Section titled “Databases move into containers”v0.10.0 runs every managed database in a container and no longer manages the engines earlier versions installed on servers. Those keep running, but Falak forgets them: no backups, no references. The update’s migration refuses to run while such databases are registered, and nothing changes:
Falak v0.10 runs every database in a container and no longer manages the host databases of earlier versions …- Back up every database you need (a dump of each, kept outside Falak).
- Set
FALAK_DROP_LEGACY_DATABASES=1in/opt/falak/custom.envand runfalak-ctl updateagain. The old rows, their backup history and their canvas services go; references to them fail until they point at new services. - Create database containers (canvas → + Create → Database) and restore your dumps into them. Point the references at the new services, then remove the flag.
Backups taken before encryption can no longer be restored from Falak.
Update every agent
Section titled “Update every agent”From v0.10.0 the control plane sends no commands to an agent whose version differs from its own. Until a server’s agent is updated it shows Update the agent on <server> and receives nothing — no deploys, no database operations. Update them right after the control plane: Servers → Update all agents, or one by one (see Agent upgrades).
After its agent update, each server is provisioned again automatically and gets Docker with live-restore: every server runs Docker now.
Resource limits
Section titled “Resource limits”Services can have memory, CPU, process, restart, log and OOM limits. The upgrade sets none: every existing site, Compose service, worker and daemon keeps running without limits until you set them. Only services created after the upgrade outside a production environment start with that environment’s defaults (512 MB, 1 CPU, 512 processes, 20 MB × 3 log files). See Resource limits.
Disaster recovery
Section titled “Disaster recovery”FALAK_BACKUP_PASSPHRASEandFALAK_BACKUP_S3_*are no longer read from.env. Runfalak-ctl dr setupwith the same bucket and passphrase (it stores them in/opt/falak/dr/dr.env), then delete them from.env. Encrypted backups taken before need that passphrase.- The cron line from earlier docs (
/etc/cron.d/falak-backup) is replaced byfalak-backup.timer: remove it. - Backups are
*.fdrnow (encrypted and authenticated) and also holdedge-pki; restoring an older backup keeps this host’s. Older*.tar.gz.encbackups restore from local files only, never from the bucket: take a new backup (falak-ctl backup --upload) after upgrading. - Installs with several organizations: set
FALAK_DR_ORGANIZATION(the operator organization’s id) in.envand runfalak-ctl up, or nobody sees the control plane’s DR.
See Disaster recovery.
Previews
Section titled “Previews”Webhooks created before v0.10.0 don’t send pull request events. To use preview environments, re-save the site’s push-to-deploy, or add the pull request events at the provider.
Checklist
Section titled “Checklist”| ☐ | New falak-ctl installed, falak-ctl update --version v0.10.0 done |
| ☐ | Emergency kit exported, stored offline, deleted from the host |
| ☐ | Old host databases dumped, recreated as containers, restored, references updated |
| ☐ | Every agent updated |
| ☐ | falak-ctl dr setup run; FALAK_BACKUP_* removed from .env; old cron line removed |
| ☐ | falak-ctl doctor clean |