Upgrade Falak
Upgrades are one command. falak-ctl takes a backup first and rolls back automatically if anything fails.
sudo falak-ctl update # latest releasesudo falak-ctl update --version v0.2.6 # a specific releaseWhat an update does
Section titled “What an update does”- Takes a backup:
backups/falak-backup-<ts>-pre-update-<old version>.tar.gz. - Fetches the new deploy bundle (checksum verified) and pulls the new images. If a pull fails, nothing changes.
- Recreates the stack. The
control-planeservice runs the migrations;horizon,reverbandschedulerwait until it is healthy. - Recreates every service whose mounted config files changed, and prints their names.
- Health-checks every container and
https://<domain>/up. - Removes older Falak images (see below).
- 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.
Old images
Section titled “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-runlists what it would remove). - Set
FALAK_PRUNE_IMAGES=0in/opt/falak/.envto 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-imagesstill works there and warns first.
The built-in registry (0.5.0)
Section titled “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.
Upgrading to v0.10.0
Section titled “Upgrading to v0.10.0”v0.10.0 is a breaking release: install its falak-ctl before updating, save the emergency kit, move host databases into containers, and update every agent right after. See Upgrading to v0.10.0.
Upgrading to v0.13.0 – v0.18.0
Section titled “Upgrading to v0.13.0 – v0.18.0”These releases add features without breaking changes: update with falak-ctl update --version <tag>, then update the agents. A few things to know:
- v0.13.0 adds the
relayservice to the compose stack (consoles and terminals);falak-ctl updatestarts it. - v0.14.0 – v0.18.0: most new data comes from the agents, each feature behind an agent feature flag. Until you update the agents, the panel keeps showing what it showed before and asks for an update where something is missing.
- v0.16.0 database metrics need the v0.16.0 database images (v0.16.2 for PostgreSQL top queries). Updating an instance’s image recreates its container on the same volume, so do it from the instance page when it suits you; the upgrade itself never restarts a database.
- v0.17.2 reloads each server’s firewall once after the agent update to add rule counters (same rules, atomic).
The changelog lists each release’s upgrade steps.
Upgrade the agents
Section titled “Upgrade the agents”An update does not touch your servers. Since v0.10.0 the control plane sends no commands to an agent whose version differs from its own, so update agents right 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
Section titled “Upgrading from 0.2.x”Mounted config files (falak-ctl v0.2.5 and older)
Section titled “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-configsThe PHP thread hotfix
Section titled “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 upfalak-ctl doctor reports the line until you remove it. See Performance.
Laravel sites logging to stderr
Section titled “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
Section titled “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)
Section titled “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.