Upgrading Self-Hosted Provon

Compatibility Policy#

Provon uses semantic versioning (MAJOR.MINOR.PATCH):

• MAJOR: Breaking changes that require manual intervention or a documented migration path.
• MINOR: New features and backward-compatible schema migrations.
• PATCH: Bug fixes and security patches.

Node deployments use forward-only database migrations. Cloudflare deployments use forward-only D1 migrations. Running an older application against a newer schema is not supported.

Before Every Upgrade#

1. Read the GitHub Release notes for the target version.
2. Check the version-specific upgrade notes (docs/upgrades/v<version>.md) if one exists for the target release.
3. Create a coordinated backup of metadata, metering, telemetry, blobs, model weights, and AUTH_SECRET. Runtime process state is kept in memory only and does not need to be backed up.
4. Verify the backup in an isolated environment before touching production.
5. Record the current application version and configuration revision.

Upgrade Steps (Node / Docker)#

1. Stop new traffic at the reverse proxy.
2. Allow in-flight requests and background work to finish.
3. Send SIGTERM and wait for graceful shutdown.
4. Back up the persistent data directory.
5. Start one new container or process with the target image/version against the same data directory.
6. Wait for startup migrations to complete.
7. Run verification checks:
   • GET /healthz
   • Sign-in
   • Project API key creation
   • OTLP ingest
   • Gateway request and trace visibility
   • Diagnostic Rule execution
   • Connector actions, if enabled
8. Resume traffic only after all checks pass.
9. Retain the previous image until the release is accepted.

Do not run old and new Node processes concurrently against one local data directory.

Upgrade Steps (Cloudflare)#

1. Read release notes and version-specific upgrade notes.
2. Run pnpm test:cf.
3. Export D1 metadata and metering databases.
4. Apply any required Data Catalog maintenance changes.
5. Run pnpm deploy:cf.
6. Verify each surface and the complete asynchronous evidence path.
7. Watch queue lag, D1 errors, warehouse writes, and R2 SQL reads through the rollout window.

Rollback#

Rollback is only safe before the new version applies migrations. Once metadata or metering migrations run, the schema is forward-only. To recover:

1. Stop the new process.
2. Restore the data directory or D1 export from the pre-upgrade backup.
3. Start the previous application version against the restored data.
4. Verify end-to-end before resuming traffic.

Version-specific upgrade notes#

Individual Provon releases that need steps beyond this general guide have version-specific notes in docs/upgrades/v<version>.md. These files are linked from the GitHub Release notes when they exist.

Compatibility Matrix#

Update this table with each release that changes the upgrade path.