Skip to content

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.

  1. 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).
  2. Back up Falak itself: sudo falak-ctl backup (the update takes one too).
  3. Keep APP_KEY unchanged until the update has finished.

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:

Terminal window
curl -fsSL https://github.com/falak-sh/falak/releases/download/v0.10.0/falak-ctl -o /usr/local/bin/falak-ctl
chmod 755 /usr/local/bin/falak-ctl
falak-ctl update --version v0.10.0
falak-ctl kek export /root/falak-emergency-kit.txt # then store it offline and delete it here

During 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.

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 …
  1. Back up every database you need (a dump of each, kept outside Falak).
  2. Set FALAK_DROP_LEGACY_DATABASES=1 in /opt/falak/custom.env and run falak-ctl update again. The old rows, their backup history and their canvas services go; references to them fail until they point at new services.
  3. 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.

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.

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.

  • FALAK_BACKUP_PASSPHRASE and FALAK_BACKUP_S3_* are no longer read from .env. Run falak-ctl dr setup with 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 by falak-backup.timer: remove it.
  • Backups are *.fdr now (encrypted and authenticated) and also hold edge-pki; restoring an older backup keeps this host’s. Older *.tar.gz.enc backups 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 .env and run falak-ctl up, or nobody sees the control plane’s DR.

See Disaster recovery.

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.

☐ 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