Upgrading
A new release of Frontforge Report Server is a new image. Upgrading means running that image on the data you have: reportd backs the data up and upgrades its format when it starts, and everything else carries on as it was. Your licence, users, templates, published versions and settings all stay.
Before you start
- Read the release notes in report-server-releases. They say what changed, and anything you need to do.
- Take a backup you can keep somewhere else:
reportd backup(backup.md). reportd takes one of its own before it changes anything, but that one stays on the same volume as the data. - Pre-releases (a version with a
-, such as0.9.1-rc.1) are for trying out, not for production. The version check never offers them (updates.md).
Compose
In your clone of report-server-releases, bring compose/ to the new release, then pull its image and start it:
git pull # on main, the newest release, or release/<x.y>, the newest of a line
docker compose pull
docker compose up -dOr check out the release's tag: git fetch --tags && git checkout v<version>. compose/docker-compose.yml names the release's image, and git leaves your .env and secrets/ as they are. If your .env sets REPORTD_IMAGE, as one copied from an older release's .env.example does, it holds you on that image: remove the line. To go back, check out the old release's tag and restore a backup taken before the upgrade.
From a compose .zip (0.9.0 and 0.10.0-rc.1 shipped one): clone the repository, copy your .env and secrets/ into its compose/, remove REPORTD_IMAGE from .env, and run the commands above from there. The project is still named report-forge, so it finds the same report-forge_data volume, and the new image starts on your data.
Docker without compose
Stop the container and start the new image's tag with the same volume, environment and port:
docker run -d --name reportd -p 43123:43123 -v reportd-data:/data ghcr.io/frontforge-corporation/report-server:<version>Helm
The chart runs the image of its own version unless image.tag says otherwise. Upgrade the release with the new chart, or set image.tag to the new version, and helm upgrade it (helm.md).
Several nodes, or renderd on its own
Run one release everywhere. renderd on its own (the split add-on, or the chart's renderd Deployment) is upgraded with reportd, to the same version. With state.driver: postgres, stop every reportd, upgrade them, and start one first: it upgrades the shared schema, under a lock, before the others join (state.md).
What happens to the data
When the new reportd starts, it reads each part's data format (migrations.md):
- Nothing to do: it starts as usual.
- An older format: it first writes a backup of the data as it was to
dataDir/backups/pre-migrate-<time>.tar.gz(/data/backupsin the image), then upgrades it one step at a time and logs each step. A stop part-way resumes at the next step. - Reports written in an older version of RFML are upgraded when they're opened. A draft is stored in the new form, as a revision of its own, the next time it's saved; a published version is upgraded in memory each time it renders, until its next publish.
With migrations.auto: false, reportd doesn't upgrade anything by itself: it refuses to start and names the steps, which reportd migrate runs while it's stopped.
Going back
reportd never downgrades data, and an older release refuses data a newer one has written. To go back to the previous release, restore a backup taken before the upgrade, either yours or the pre-migrate one, with the previous release's reportd restore (backup.md), then start the previous release. Copy the pre-migrate backup out of the volume first (docker compose cp reportd:/data/backups/<file> .), because a restore moves the old data aside.
How a release is tested
Every release, from 0.10.0 on, is tested by upgrading the last stable release before it, before it is published: 0.10.0 and its release candidates upgrade 0.9.0. The test runs that release's published image on an empty data folder, as an install would, and gives it what an install has: users, one of them signed in, an API key, a library with a release, a data source on an operator's connection, published templates, drafts, and a finished batch job with its reports. Then it stops that image, starts the new release on the same data, and checks that:
- the data was backed up to
pre-migrate-<time>.tar.gzbefore anything changed, and then upgraded; - the server is ready (
/readyz) and says it is the new version; - whoever was signed in stays signed in, passwords still sign in, and API keys still work;
- every template is there, with its published version and its draft as they were, and so are the library's release, the data source and the connection;
- the published templates lay out exactly as they did, page by page, with the same text;
- the drafts open in the designer;
- the finished job and its reports are kept, and new jobs run.
Your licence
A licence stays installed through an upgrade. A Community licence never expires, and a paid licence carries on to its own expiry date (licence.md).