Upgrades

Moving a self-hosted Floot backend to a newer Supabase release: pinned tags, every upgrade treated as a migration-compatibility event, and update.sh.

The stack stays on the release tag you installed until you move it. This page covers when to move, how to prove the kit's migrations still apply on the new tag before production sees it, and the upgrade itself.

Pin a release tag and upgrade on purpose: for a security advisory, a feature you need, or a look at upstream's changelog once a month. The stack moves fast, and the kit depends on what its services do: the migrations need Realtime's realtime.messages with row level security on, and the Postgres image's extensions (pg_net, pg_cron, pgmq, pg_jsonschema, Vault). So treat every upgrade as a migration-compatibility event:

Read the new release's CHANGELOG.md and upgrades.json. Past releases changed what API_EXTERNAL_URL holds (0.7.0) and replaced the Kong gateway with Envoy (0.8.0).
On a scratch copy of the stack at the new tag, apply every migration from an empty database and exercise your functions.
Take a backup.
Upgrade: sh update.sh --dry-run, then sh update.sh --to self-hosted/v<x.y.z>. It merges upstream's files against the tag in .supabase-version, appends new .env.example keys to .env without touching existing values, and asks before a release upgrades.json marks as breaking. A conflict leaves merge markers and exits with status 2; resolve it by hand. It also lists every key of your # Floot app block under ".env keys you have that are gone from the new .env.example (review/remove manually)": those are yours, not upstream's, so keep them; the update leaves them as they are. Then sh run.sh pull and sh run.sh recreate.

A Postgres major upgrade is a project of its own, never part of a routine upgrade.

Floot's setup. An upgrade is a pull request that re-vendors upstream at the new tag with a small script and shows the diff. Each new .env.example key is decided by hand: a secret goes into .env, any other value into Floot's compose file. A laptop stack built from the new tag must boot every service and apply every migration. Then come a backup, a release to a throwaway server, and only then production. Memory limits are measured again after each one.