Upgrade
cd /srv/flux && ./flux upgrade # the latest release; or ./flux upgrade v0.2.2 for that onev0.1 is not upgraded. v0.1.0 had no users, so Flux v0.2 converts none of its data. If the instance was
written by v0.1, ./flux upgrade refuses it and tells you to install v0.2 fresh: see below.
Everything else on this page is for an upgrade from one v0.2 version to a later one.
Which versions upgrade to which
Section titled “Which versions upgrade to which”A folder installed from any release from v0.2.1 on (the first that ships the flux launcher in flux.tar.gz) upgrades to
any later release by ./flux upgrade. Its data, files, settings, agents, encrypted spaces and sessions stay. You may skip
releases, and the migrations of the releases in between are applied in order.
| Installed release | Upgrades to |
|---|---|
| v0.2.0 | install v0.2.1 fresh (installation): v0.2.0 was installed from loose Compose files, and no v0.2.0 installation exists to carry over, so v0.2.1 brings no way to move one into a release folder. Its data would upgrade: every release is tested to upgrade v0.2.0’s data (below). |
| v0.2.1 | every later release |
This table gains a row with each release; the release notes of a release say which versions it was tested to upgrade from. Every release proves it before it is drafted (how it is tested): each of these releases is installed from its own assets, filled with data of every kind, upgraded to the candidate and read back. A release whose upgrade fails is not drafted.
The rules
Section titled “The rules”These hold for every release, and the checks below fail when one is broken. They are for people who change Flux as much as for operators: the engineering side is in upgrade compatibility.
- Migrations are forward-only and immutable once released. A file in
app/packages/db/migrations/that a release contains never changes, is never renamed and never deleted: instances have recorded it in their ledger, and the migrator refuses a ledger row without a file. A fix is a new migration with the next free number, above the highest released one. - Every migration works on the data that any earlier release from v0.2.0 on left behind, not only on an empty database or on
the data of the release just before. A backfill covers rows written by every earlier release (the missing
workspaces.companyof a v0.1 database was the example, #1176). - No migration depends on application code that a later release may delete. A migration is plain SQL that stands on its own: it does not call a function of the application, read a constant of it or assume a table that only the application creates.
- Skipping versions is supported. Any release goes straight to any later one; the migrations of the releases in between are applied in numeric order, each in its own transaction.
- A downgrade is not supported. Forward migrations are not reversible. The way back is the backup that the upgrade took first (when it fails, backup and restore).
- Configuration changes between releases are the launcher’s to handle, never silent. A new setting has a default that keeps
the old behaviour, so an old
.envkeeps working. A setting that a release renames or removes is listed indocker/env-changes.txt;./flux upgrademoves a renamed setting to its new name and prints what it did, and reports a removed one by name and reason, and the release notes list the same changes.
./flux upgrade moves the instance in this folder to a newer release (#1471,
founder decision 5):
- Download and check, while Flux runs. It downloads the release’s
flux.tar.gzandSHA256SUMS(the latest release, or the version you name, fromhttps://github.com/ColdPhase/flux/releases;FLUX_RELEASE_URLnames a mirror with the same layout). The archive must match its line inSHA256SUMS, andSHA256SUMSmust carry the release workflow’s signature, always; otherwise it refuses and nothing changes. Without network access, download both files yourself and run./flux upgrade --file flux.tar.gz(withSHA256SUMSandSHA256SUMS.sigstore.jsonbeside it). It refuses an older release, or one whose schema is older than the data (a downgrade) and says so when this folder already runs that release. - Pull the new images, while Flux runs. The images that the new
docker/release.envnames, pinned by digest (the agent runtime’s only while it is on), so the downtime does not include the download. - It asks for confirmation (
-yanswers yes) and reads the current schema from the database. - Backup. It runs
./flux backupintobackups/(or--output DIR), with one difference: API and worker stay stopped after the backup. Nothing can be written between the backup and the new version, so going back to the backup loses nothing. - New files. It keeps the current release’s files in
flux-files-<old version>-<time>.tar.gznext to the backup, puts the new release’s files in place (docker/.env,docker/compose.override.yamland your backups stay as they are) and continues in the new launcher. - Migrate forward.
files-init, then the one-shot migration applies every new migration in order, each in its own transaction. - Health. It starts API and worker, waits for their health checks, and checks that the API and the database report the release’s schema. The agent runtime, when it is on, moves to the new release’s image too.
A Flux developer’s source checkout upgrades to its own code instead: git pull --ff-only && ./flux upgrade (or
./flux upgrade --pull) builds it, with the same backup, migration and checks.
Docker Engine 25 or newer is required (the health checks need start_interval; docker compose up refuses an older
engine, see requirements). The launcher checks it before it starts. Update the engine before
an upgrade, because a launcher that finds an old one after the backup has stopped API and worker reports UPGRADE FAILED
with the way back.
The downtime is the backup and the migration. It prints
Upgraded <project> from schema A to B and keeps the backup.
The image checks the database’s migration ledger before it migrates: every recorded version must be a file of the image. If it refuses, keep the backup and restore its matching image and database. Do not edit the ledger or rename a migration to make the check pass.
Schema history: v0.1’s schema is the baseline migration 0001_v0_1_baseline.sql (#779) and
0002_first_time_user.sql (#806), schema version 2. v0.2 starts with 0003_one_company_spaces.sql, and later versions
add 0004 onwards. Development databases from before the baseline (pre-release builds) cannot be upgraded either: remove
them with ./flux clean and start again.
v0.2.1: the database image changes
Section titled “v0.2.1: the database image changes”From v0.2.1 the database runs Flux’s own image, ghcr.io/coldphase/flux-database (a source checkout builds it from
docker/database/Dockerfile), instead of the official postgres:18.6-alpine. It is the
official PostgreSQL 18 on Debian with the pg_search extension, which ranks search by BM25 (F-042).
Nothing to do by hand: the release names the new image, and ./flux upgrade pulls it and restarts the database on it before
migrating.
-
The data directory stays as it is. The same PostgreSQL major (18) reads it unchanged. The old image (musl) sorted text byte by byte; the new one (glibc) is built to sort the same way, so ordinary indexes stay valid and
ORDER BYreturns the same order as before. Thepostgresuser keeps the old image’s id (70), so file owners do not change either. -
Case and character classes differ for rare characters. For letters added to Unicode in recent years, the circled letters and a few others (about 100 characters for
lower/upper, 9,900 for word and trigram splitting), the two C libraries disagree. Polish, English and the common scripts are unaffected. Migration0065therefore recomputes what was derived from those functions under the old image: the stored search columns of the rows whose values differ, and every index built from an expression (such aslower(email)), a text-dependent condition or a method other than B-tree. Nothing to do by hand. -
Migration
0065also creates the extension and the search index, and three later migrations rebuild it:0085(the joined-words fields),0088(a name row for every file, which grows with the number of files) and0093(a REINDEX ofsearch_documents). Measured on a v0.2.0 installation with its test content and 302,000 more messages, upgraded to the train head44947da84by./flux upgrade -y(2026-11-17, a busy 24-core host, so upper bounds). In the second of two runs, with the migrations’ times taken as the gaps between the ledger’sapplied_at,0065took 29 s,00855 s,00935 s and00880.03 s (that data has few files), and migrations0054to0094together 40 s; the whole./flux upgrade, with its images already built, took 81 s in the first run and 107 s in the second. Expect more on a larger database. API and worker are stopped meanwhile, so count it in the downtime. On a database that is not running Flux’s image (for example your own PostgreSQL), it stops withFLUX_DATABASE_IMAGE Flux v0.2.1 needs its own database image …before it changes anything; API and worker do not start. Run./flux upgrade, or installpg_searchin your PostgreSQL and add it toshared_preload_libraries. -
Backups keep working the same way: a dump holds the index’s definition, and a restore rebuilds it. A backup from before the upgrade restores with the old release’s files, as always (when it fails).
-
Settings of your own. The image’s entrypoint adds
pg_searchtoshared_preload_librariesand turns pg_search’s custom scan and planner notes off unless you set them: on the command line, inpostgresql.confor withALTER SYSTEM. A list of preloaded libraries you set keeps its entries and gainspg_search. -
Memory and disk. The memory limits are unchanged. The image is about 500 MB larger (800 MB); the index adds about 4 MB per 10,000 messages.
-
The files already sent are read for search (C-63, #1382). Migration
0072queues every PDF, DOCX, Markdown, text, CSV and TSV file of the plain spaces and gives each its name as a search row at once; the worker reads their text in the background, one file at a time in a sandboxed child process, as soon as it starts; how long that takes depends on the number and size of the files, and nothing else waits for it. Until a file is read it is found by its name only; one that cannot be read (a scan, a password) stays found by its name. Nothing to do by hand. The sandbox needs the image’ssandbox.node: a worker started from a source tree without it reads no file and says so once in its log.
v0.2.1: HTTPS and calls come from the launcher
Section titled “v0.2.1: HTTPS and calls come from the launcher”From v0.2.1 (#1471) an https FLUX_PUBLIC_ORIGIN with an empty
FLUX_TRUSTED_PROXIES starts the built-in HTTPS proxy on ports 80 and 443. This is the one
exception to rule 6: an instance behind a proxy of its own whose FLUX_TRUSTED_PROXIES is still empty would see the new proxy
fail on the ports its own proxy holds. Set FLUX_TRUSTED_PROXIES to that proxy’s address
(how), as the installation guide already asked, before you upgrade; or stop your own
proxy and let Flux’s take over. The new FLUX_CALLS is off unless you set it (calls).
From v0.1: install v0.2 fresh
Section titled “From v0.1: install v0.2 fresh”v0.1 had no users, so v0.2 converts no data and keeps no compatibility with it (founder direction, 2026-11-09, #1176). A v0.1 instance carried over by migration would hold its old workspace but no company, and one Flux is one company: nobody could reach Settings › Company, invite links or the list of spaces. So v0.2 refuses a v0.1 database everywhere it could meet one, and changes nothing:
| Where | What happens |
|---|---|
./flux upgrade |
Reads the database’s schema and, for a v0.1 database, stops before the confirmation, the backup and the stop of API and worker. It prints that the database was written by Flux v0.1, that v0.2 does not upgrade it, and what to do instead. Your data is as it was. |
./flux upgrade --pull started by a v0.1 launcher |
The old launcher does not know, so it takes its backup and stops API and worker first. The pulled v0.2 launcher then stops before it builds anything: UPGRADE FAILED: the database was written by Flux v0.1, which v0.2 does not upgrade, with the usual way back (check out the v0.1 files and ./flux restore the backup). |
./flux up, docker compose up |
The one-shot migrate service refuses before any migration file runs: FLUX_V01_DATABASE This database was written by Flux v0.1 (schema 2). Flux v0.2 does not upgrade it …, exits 1, and API and worker do not start. Compose has replaced v0.1’s API and worker by stopped containers by then, so v0.1 is down until you check out its v0.1.0 files and run ./flux up. The data is untouched. |
./flux restore |
Refuses a v0.1 backup with and without --migrate, before it replaces any data. Restore it with a v0.1 checkout. |
A v0.1 database is one whose migration ledger stops before 0003 and that holds an account or a workspace. A first
installation that was interrupted after 0002 and before anybody signed up is not refused: it migrates on.
What to do:
- Keep what you need. Using v0.1,
./flux export <space>writes a space as open JSON plus files (export) and./flux backupan archive of the whole instance. Neither v0.1 nor v0.2 can import an export, so it is for reading and keeping; the backup restores only on a v0.1 checkout. - Install v0.2 fresh. Either in a new folder, with its own
FLUX_PROJECT, volumes and port (installation), or in the same folder after./flux reset, which deletes this instance’s data after you confirm. Do not point v0.2 at v0.1’s volumes. - Set up first. The first account on the new Flux, made from the setup link
./flux upprints, sets up the company and owns it; then invite everyone else.
Signatures
Section titled “Signatures”Every release’s SHA256SUMS is signed keylessly by its release workflow (final-release.yml,
cosign with GitHub’s OIDC identity; the signature is the release asset SHA256SUMS.sigstore.json). SHA256SUMS holds the checksum
of flux.tar.gz, whose docker/release.env pins every image by digest, so one signature covers everything Flux runs; the images
are signed by the same workflow too.
./flux upgrade always checks it (founder decision, 2026-11-13, F-043).
The identity is pinned: https://github.com/ColdPhase/flux/.github/workflows/final-release.yml@refs/heads/main, issued by https://token.actions.githubusercontent.com. It uses
cosign when this machine has it, and otherwise the official cosign
image, pinned by digest (ghcr.io/sigstore/cosign/cosign:v3.0.6@sha256:de9c65609e6bde17e6b48de485ee788407c9502fa08b8f4459f595b21f56cd00), through Docker: that container gets only SHA256SUMS and its signature, read-only, no
capabilities and no other file of the server, and it reaches the network for Sigstore’s trust root. The upgrade is refused, with
nothing changed, when the signature is missing, does not verify, or cannot be checked.
Offline (./flux upgrade --file). Keep SHA256SUMS.sigstore.json beside flux.tar.gz and SHA256SUMS. A server without
internet access needs the cosign image loaded once: docker pull ghcr.io/sigstore/cosign/cosign:v3.0.6@sha256:de9c65609e6bde17e6b48de485ee788407c9502fa08b8f4459f595b21f56cd00 on a connected machine, docker save it into a file,
carry it over and docker load it. The check also needs Sigstore’s trust root, so on a fully offline server it fails, and the
upgrade with it; check the files on a connected machine instead (the command of the installation).
When it fails
Section titled “When it fails”If any step fails, the launcher stops the API and worker, confirms that both are stopped, and prints how to go back. What it says about your data depends on how far the upgrade got:
- Before the new version started (build, files volume or migration failed): the writers were stopped since the backup, so nothing was written after it.
- After the new version started (start, health or schema check failed): the new API and worker
may have accepted work between the start time it prints and the failure. That work is not in the
backup, and restoring the backup discards it; take another
./flux backupfirst if you need it. - If a writer cannot be stopped, it says so and names it; stop it yourself before restoring.
UPGRADE FAILED: the migration failedYour data from before the upgrade is in /srv/flux/backups/flux-backup-flux-3f2a9c1d-20260928T091502Z.tar (schema 10, commit 841ddc9…).API and worker stayed stopped since that backup, so nothing was written after it.To go back: tar -xzf '/srv/flux/backups/flux-files-v0.2.1-20260928T091504Z.tar.gz' -C '/srv/flux' # the release files you ran before ./flux restore '/srv/flux/backups/flux-backup-flux-3f2a9c1d-20260928T091502Z.tar'Or fix the cause in this checkout and run ./flux restore '…' --migrate to retry the upgrade.The first line puts the previous release’s files back, so ./flux restore runs the previous release’s images on the backup.
A failed migration file rolls back its own transaction; earlier new migrations of the same upgrade stay applied, which is why the instructions restore the backup rather than restarting the old version on the partly migrated database.
Tested with
Section titled “Tested with”./scripts/check_upgrade_matrix.sh (upgrade compatibility) is the proof
of the rules above. For every published release from v0.2.0 on before the candidate it
installs the release from its own release assets (its Compose file and settings template, in flux.tar.gz from v0.2.1 on, and its images by digest) and
fills it through the API with what an installation holds after use: people and a guest, spaces including an encrypted one, threads,
direct messages, files, wiki history, maps, tasks with due dates and waits, notification settings, a second signed-in device,
an API-key AI connection, and an agent with memory and schedules that has run. It upgrades that installation to the candidate’s
Compose file and images, then reads everything back, checks that the second device’s session still works, unlocks the encrypted
space with its password, checks that a schedule’s next times lie ahead, and writes new work, including a new agent run on a provider
mock. The upgraded installation and the pre-upgrade backup are restored into fresh volumes. The same is repeated for a source
checkout of each release: its tree is started with ./flux up, seeded, replaced by the candidate’s tree and moved with
./flux upgrade -y. Each release goes straight to the candidate, so the older ones also prove that versions can be skipped. Against the oldest
release it also adds a migration that breaks old data: the upgrade must stop, API and worker must not start, and the paired backup
must restore into fresh volumes with that release’s files and read back. Before any of this, scripts/release/check_released_migrations.py
checks that every released migration file is byte-identical to the one in its release tag. A negative control for each failure
(FLUX_MATRIX_CONTROL=edited-migration and old-data) must fail the check.
scripts/release/smoke_launcher.sh runs the owner’s path itself on the candidate’s own images: the download check, ./flux up,
backup and restore, ./flux upgrade from a release URL to the next release with the signature checked through the pinned cosign
image (a throwaway key stands in for the release workflow’s identity, which signs only on GitHub), and its refusals of an archive that
does not match SHA256SUMS and of a SHA256SUMS signed by another key (nothing changes and Flux keeps running).
final-release.yml runs the upgrade from the previous release in its package job and
the matrix of every earlier release in its upgrade job; the draft is not made when either fails, and its notes name the versions
it was tested to upgrade from. app/tests/app/released-databases.test.ts runs the real migrator on a database dumped from each
release, in ./scripts/check_application.sh.
./scripts/check_backup.sh tests an upgrade from the previous version (the newest main commit with other migrations since v0.2’s first
one, 0003, or FLUX_UPGRADE_FROM; before such a commit exists, this tree, upgraded to this tree plus one synthetic next
migration), seeds it, upgrades it with ./flux upgrade -y, and checks the applied migrations, the backup it made and the data
through the API. It then adds a failing migration, checks that the upgrade fails with the restore instructions above, and
follows them. With FLUX_UPGRADE_FROM=v0.1.0 it starts v0.1.0 with its demo instead and checks the refusals of the table
above: ./flux upgrade, the migrator and ./flux restore refuse it with the plain message, write no backup, change nothing,
and leave v0.1 running at schema 2. FLUX_BACKUP_CASES=upgrade runs only this part. The refusal itself is also covered by
app/tests/app/migrate-v01-database.test.ts (the real migrator and the restore gate on a scratch database that holds what
v0.1 wrote) and app/tests/app/migration-ledger.test.ts.