Skip to content

Upgrade

Terminal window
cd /srv/flux && ./flux upgrade # the latest release; or ./flux upgrade v0.2.2 for that one

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

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.

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.

  1. 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.
  2. 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.company of a v0.1 database was the example, #1176).
  3. 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.
  4. 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.
  5. 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).
  6. 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 .env keeps working. A setting that a release renames or removes is listed in docker/env-changes.txt; ./flux upgrade moves 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):

  1. Download and check, while Flux runs. It downloads the release’s flux.tar.gz and SHA256SUMS (the latest release, or the version you name, from https://github.com/ColdPhase/flux/releases; FLUX_RELEASE_URL names a mirror with the same layout). The archive must match its line in SHA256SUMS, and SHA256SUMS must 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 (with SHA256SUMS and SHA256SUMS.sigstore.json beside 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.
  2. Pull the new images, while Flux runs. The images that the new docker/release.env names, pinned by digest (the agent runtime’s only while it is on), so the downtime does not include the download.
  3. It asks for confirmation (-y answers yes) and reads the current schema from the database.
  4. Backup. It runs ./flux backup into backups/ (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.
  5. New files. It keeps the current release’s files in flux-files-<old version>-<time>.tar.gz next to the backup, puts the new release’s files in place (docker/.env, docker/compose.override.yaml and your backups stay as they are) and continues in the new launcher.
  6. Migrate forward. files-init, then the one-shot migration applies every new migration in order, each in its own transaction.
  7. 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.

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 BY returns the same order as before. The postgres user 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. Migration 0065 therefore 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 as lower(email)), a text-dependent condition or a method other than B-tree. Nothing to do by hand.

  • Migration 0065 also 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) and 0093 (a REINDEX of search_documents). Measured on a v0.2.0 installation with its test content and 302,000 more messages, upgraded to the train head 44947da84 by ./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’s applied_at, 0065 took 29 s, 0085 5 s, 0093 5 s and 0088 0.03 s (that data has few files), and migrations 0054 to 0094 together 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 with FLUX_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 install pg_search in your PostgreSQL and add it to shared_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_search to shared_preload_libraries and turns pg_search’s custom scan and planner notes off unless you set them: on the command line, in postgresql.conf or with ALTER SYSTEM. A list of preloaded libraries you set keeps its entries and gains pg_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 0072 queues 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’s sandbox.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).

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:

  1. Keep what you need. Using v0.1, ./flux export <space> writes a space as open JSON plus files (export) and ./flux backup an 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.
  2. 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.
  3. Set up first. The first account on the new Flux, made from the setup link ./flux up prints, sets up the company and owns it; then invite everyone else.

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

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 backup first 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 failed
Your 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.

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