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:

docker compose pull || docker compose build
docker compose down
docker compose up -d

The || docker compose build covers the period before the first image is published; once it is, the pull succeeds and the build never runs.

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.