Upgrade Falak

Upgrades are one command. falak-ctl takes a backup first and rolls back automatically if anything fails.

sudo falak-ctl update                   # latest release
sudo falak-ctl update --version v0.2.6  # a specific release

What an update does

1. Takes a backup: backups/falak-backup-<ts>-pre-update-<old version>.tar.gz.
2. Fetches the new deploy bundle (checksum verified) and pulls the new images. If a pull fails, nothing changes.
3. Recreates the stack. The control-plane service runs the migrations; horizon, reverb and scheduler wait until it is healthy.
4. Recreates every service whose mounted config files changed, and prints their names.
5. Health-checks every container and https://<domain>/up.
6. Removes older Falak images (see below).
7. Prints how many server agents are older than the shipped build.

If step 3, 4 or 5 fails, falak-ctl rolls back automatically: it restores the previous deploy files and FALAK_VERSION, restores the database, storage and Fleet CA from the pre-update backup (the new migrations may already have run), and starts the previous version again.

Caution

--skip-backup skips step 1, so there is nothing to roll back to. Do not use it in production.

Old images

Each release pulls new falak-control-plane, falak-edge and falak-builder images (about 1 GB together), so a host that updates often fills its disk. After a successful update, falak-ctl records the version it came from as FALAK_PREVIOUS_VERSION in .env and removes every other tag of those three images. The current and the previous version stay, so a manual rollback (falak-ctl update --version <previous>) needs no download.

• Third-party images (Postgres, Valkey, Grafana, …), images still used by a container and volumes are never touched.
• Run it on its own with sudo falak-ctl prune-images (--dry-run lists what it would remove).
• Set FALAK_PRUNE_IMAGES=0 in /opt/falak/.env to keep every image.
• With FALAK_PULL=0 (images built locally, e.g. --build-from-source), an update never prunes: removed images could not be pulled again. falak-ctl prune-images still works there and warns first.

The built-in registry (0.5.0)

Falak 0.5.0 adds a built-in image registry for Docker builds. falak-ctl update adds FALAK_REGISTRY_* to .env and writes the weekly garbage collection cron entry. If the update was run by an older falak-ctl, run sudo falak-ctl up once afterwards. Then create the registry.<domain> DNS record and check it with sudo falak-ctl registry status. See The built-in image registry.

Containers reaching databases on their own server need agent 0.4.5 or newer; update the agents (below).

Upgrade the agents

An update does not touch your servers. Update agents afterwards from Servers (per server, the ones you select, or Update all agents) or through the API. See Agent upgrades.

Upgrading from 0.2.x

Mounted config files (falak-ctl v0.2.5 and older)

An update replaces /opt/falak/observability/ and /opt/falak/deploy/, but a running container keeps the files it was started with, and docker compose up only recreates services whose compose definition changed. falak-ctl v0.2.5 and older did not detect this, so Loki could keep an old loki.yaml (access logs in Network Logs were then not queryable).

An update is run by the already installed falak-ctl. After updating from v0.2.5 or older, run once:

sudo falak-ctl reload-configs

The PHP thread hotfix

If you added FRANKENPHP_CONFIG=num_threads 24 to /opt/falak/custom.env on 0.2.x, the update keeps working: a thread count in FRANKENPHP_CONFIG still wins over the automatic sizing (containers log a notice). It is no longer needed, because agents now long-poll their own agent-api service. Remove the line, then:

sudo falak-ctl up

falak-ctl doctor reports the line until you remove it. See Performance.

Laravel sites logging to stderr

Falak migrated Laravel sites that used LOG_CHANNEL=stderr (the old default) to daily, as a new environment version effective on their next deployment. Redeploy Laravel sites to get their web request logs into Loki. The migration cannot tell a deliberate stderr from the old default; set it back if you really want stderr.

Releases deployed before the permission hardening

Release and shared/ directories are now closed to other local users (mode 0750 plus an ACL for the edge). Releases deployed before stay open until they are pruned; redeploy each site a few times (or enough to exceed Releases to keep) to replace them.

Releasing (maintainers)

Pushing a tag vX.Y.Z (vX.Y.Z-rc.N for pre-releases, which are not tagged latest) runs .github/workflows/release.yml, which builds multi-arch falak-control-plane, falak-builder and falak-edge images to ghcr.io/<owner>/…:<tag> and :latest, builds falak-agent, falak and falak-builder binaries, and creates the GitHub release with the binaries, falak-deploy.tar.gz, install.sh (pinned to the tag), falak-ctl and SHA256SUMS. After the first release, make the three GHCR packages public so hosts can pull anonymously.

Next steps

Agent upgradesBring servers up to date.

Backup and restoreWhat the pre-update backup contains.