Upgrading

Take a backup first. Migrations run automatically on boot and some of them cannot be undone, so this is the one step worth never skipping:

./backup.sh /var/backups/lyraflow

Then move the checkout to the release and pull its image. Every release tag publishes ghcr.io/lyraflow/lyraflow for amd64 and arm64:

git fetch --tags
git checkout vX.Y.Z
docker compose pull && docker compose up -d

Check out the tag before pulling, not after. The compose file, install.sh and the backup scripts come from the checkout, and a new image can expect a compose file that only the new tag has.

docker-compose.yml names the image ghcr.io/lyraflow/lyraflow:0, and :0 means the newest 0.x release. So a checkout left on an older tag still pulls the newest image, not the one that matches it. To hold an install at one version, name that version in .env as LYRAFLOW_IMAGE=ghcr.io/lyraflow/lyraflow:X.Y.Z. Every release is also published as X.Y, X and, for a final release, latest. Releases older than the first published image have no image; build those with docker compose build.

If you have modified your checkout, build it instead of pulling: docker compose build && docker compose up -d. The build writes the same local tag, so a later docker compose pull replaces your build with the published image.

The restart itself loses nothing. Accepted events are flushed before shutdown, migrations run on boot, and the ClickHouse identity dictionaries are rebuilt from Postgres every time rather than migrated, so they are never left stale.

If the new version will not start, check the logs for a schema-version error. Downgrading the image below the schema in your database is refused deliberately — the remedy is to put the newer image back, or restore the backup you took above.

Upgrading to the release that added retention

Retention prunes old events, and the first version to enforce it acts on whatever retention_months each project already had. That column has existed since the first migration and nothing ever applied it, so the value being enforced may be one nobody has looked at in a long time. Check before you upgrade:

docker compose exec postgres psql -U lyraflow -d lyraflow \
  -c 'SELECT id, slug, retention_months FROM projects ORDER BY id'

Upgrading changes none of those values — the 13-month default applies only to projects created afterwards. If you would rather it did not start yet, add

      LYRAFLOW_RETENTION_ENABLED: "false"

to the environment: block of the lyraflow service in docker-compose.yml, before starting the new version. It has to go there and not in .env: Compose uses .env for substitution inside the compose file and passes the server only the variables that block names, so retention would run anyway. Nothing is dropped for age until you turn it back on.