Upgrading

Parley

Pull the new tag and docker compose up -d. Migrations run automatically at boot.

On Kubernetes it is helm upgrade with the new --version and --reuse-values — the procedure, and the checks that prove the pods actually rolled, are on Kubernetes. Under ArgoCD or Flux there is no --reuse-values and no helm test; see GitOps.

After upgrading a multi-replica install, confirm the replicas are still on different nodes — kubectl get pods -o wide. The chart makes a rollout much less likely to collapse them onto one, but the constraint is a preference rather than a guarantee, and on Kubernetes older than 1.27 the mitigation is absent entirely; see Rollouts.

Rolling back an image is only safe if the newer version didn’t add migrations. If it did, Parley refuses to start and says so, rather than running against a schema it doesn’t understand. Restore from a backup instead.

Upgrading to v0.5.0: organizations

v0.5.0 puts every space inside an organization. The migrations that do it (0021–0023) are forward-only — there is no down path and no rollback. Take a backup first and check that you can restore it; if the upgrade goes wrong, restoring that backup is the only way back.

If you run one team on one instance, nothing visible changes

The migration creates one org, called default, and puts every existing space and every existing account in it. You do not have to create anything, configure anything, or tell anybody. Concretely:

• Your links keep working. A /s/{slug} address redirects to the space’s new /o/{org}/s/{slug} home, resolved against the caller’s own memberships. Someone who is not signed in — or a guest holding a signed session link — is served the app exactly as before. A signed-in caller who has no matching membership, or more than one, gets a 404 rather than a redirect: the address names one space and Parley will not guess which org you meant.
• Signed session links are untouched. They address a session, not a space, and they never carried an org segment.
• Existing spaces become “unlisted”. This is a change in discoverability only. Nothing about who can open a space or what they see changes: a stranger who opens a link to an existing space still gets its name and whether a passcode is set, exactly as they did the day before the upgrade. Being unlisted only means the space is not in the org directory, a screen that did not exist yesterday.
• Passcodes still do the same job. Visibility governs discovery; the passcode governs entry, including for members of your org.

New spaces you make after the upgrade are listed in the directory by default, and their owner can unlist them at any time. In open mode every space is unlisted and the directory stays empty.

If you run more than one team

Read Organizations and claim mapping before you upgrade. It covers creating a second org, pointing it at one of your provider’s groups, and bootstrapping the first admin — and Organizations covers what the person administering an org can then see, which is worth being able to answer before somebody asks.

Upgrading to the release that adds session lifetimes

This release introduces SESSION_MAX_TTL, an absolute cap on how long a session may live measured from the moment it was issued, and nothing renews it. Before it, expiry was purely idle: a token that kept being used never died.

Some people will be signed out by the upgrade. Every existing token whose created_at is older than SESSION_MAX_TTL — 90 days by default — stops resolving at the next request, however recently it was used, and the new hourly sweep deletes the row. On an instance that has been running for more than 90 days that is everyone who has not signed in since. They sign in again; nothing is lost. It is still worth saying so in advance, because to the person it happens to it looks like the upgrade broke their login.

If you would rather not do that in the same change as the version bump, set SESSION_MAX_TTL to something longer than the instance has existed for the first rollout, then lower it once people have been told. Both lifetimes are documented under Configuration.

Postgres

Parley supports PostgreSQL 13 and newer, with no upper bound — the compose file pins postgres:16-alpine because a compose file has to pin something. Major Postgres upgrades (16 → 17) are not automatic:

1. pg_dump with the old version
2. start fresh with the new one
3. restore

Never just change the tag on an existing volume — the data directory is not readable across major versions.