Upgrade from 0.x to 1.0
1.0 is the first release with the 1.x upgrade guarantee. After 1.0, any 1.x release upgrades to any later 1.y release without an intermediate release, as the compatibility policy states. Before 1.0, a release can require action. This page collects the actions on the way from a 0.x release to 1.0.
Upgrade owns the procedure itself: the rehearsal on a copy, the upgrade, failed-migration recovery, and rollback. The migration guide owns the full instructions of each change.
Before you start
- Find the release that the host runs on Instance administration → Overview.
- If the database has not passed the v0.77.4 cut-point, follow the database baseline prerequisites first.
- Read every migration guide entry between your release and 1.0.
- Make a database backup and verify that it restores, as Backup & restore describes.
- Keep the signed release lock and the
.envof your current release with the backup.
Several changes on the way to 1.0 need every runtime role stopped before the migration.
A server, worker, or webhook server of the old release fails when it reads the new schema or the data that the new release writes.
Stop application-server, application-worker, and webhook-server before you start any role of the new release.
Move to the Helm chart
1.0 supports only the Helm chart, as Supported deployment states.
Change the deployment or the release, never both in one step.
First, upgrade on Compose to 0.95.0.
Then use Move from Compose to the Helm chart to move that version.
The procedure requires a backup and a verified restore before the move.
Breaking changes after v0.94.7
The releases after v0.94.7 include these changes. Each row names the action and the migration guide entry that owns the procedure. The migration guide also has the entries of the releases before v0.94.7.
| Change | Operator action | Migration guide entry |
|---|---|---|
| Hephaestus keeps one conversation for each developer in each workspace. The upgrade deletes the earlier Hephaestus chat history. | Stop every role before the upgrade, then follow the entry. | Stop every role for the conversation upgrade, which deletes Hephaestus chat history |
| Production instance administration requires passkeys. | Before the upgrade, read Admin passkeys. After the upgrade, enroll two passkeys and save the recovery codes. Set the passkey origin and RP ID if the webapp uses another origin. | Admin passkey protection |
| Delayed reviews use the work that was saved when their event was recorded. | Stop every role, back up the database, and deploy matching server, worker, and webhook images. | Deploy matching runtime roles for retained review evidence |
| Logs use the Elastic Common Schema, and Sentry is removed. | Remove SENTRY_DSN. Update log queries, alerts, and dashboards for the new field names. | Update log queries for the new log format and remove SENTRY_DSN |
| The webapp container runs as an unprivileged user on port 8080. | Only if you run the webapp image outside the bundled Compose stacks: send traffic to port 8080 and mount a writable /tmp/hephaestus-webapp. | Send webapp traffic to port 8080 |
| The practice comparison API responses change. | Update clients that read /practices/workspace-overview or /practices/tiles. | Update practice comparison API clients |
Review sandboxes use SANDBOX_MEMORY_BYTES, SANDBOX_CPUS, and SANDBOX_PIDS_LIMIT. The worker refuses to start if SANDBOX_MEMORY_BYTES is below 2,751,463,424 bytes. | Only if you set SANDBOX_MEMORY_BYTES: set it to 2751463424 or more, or remove it to use the default of 3 GiB. | Keep SANDBOX_MEMORY_BYTES at 2.6 GiB or more |
| Compose forwards three item event ledger settings and the backfill item limit under their current names. Before, the application ignored the old names. | If you set SIGNAL_LEDGER_* or PRACTICE_REVIEW_BACKFILL_MAX_ARTIFACTS in .env, rename them to ITEM_EVENT_LEDGER_* and PRACTICE_REVIEW_BACKFILL_MAX_ITEMS. | None. The release notes describe it. |
After the upgrade
- Open Instance administration → Overview and read Configuration readiness.
- Resolve each item under Action required.
- Run one practice review in Approve first mode, as First steps § 7 describes.