Upgrading Self-Hosted Provon

Development Compatibility Policy#

The project is under active development. Refactors update all consumers directly, keep no compatibility shims, and maintain only the current initialization baseline. Historical data migration is not part of the development release workflow. Preserve a recovery copy before any future production schema change; application rollback does not restore data automatically.

Before Every Upgrade#

1. Read the GitHub Release notes for the target version.
2. Check for a version-specific upgrade note (docs/upgrades/v<version>.md) when one exists for the target release.
3. Create a coordinated backup of metadata, usage events, telemetry, blobs, and PROVON_AUTH_SECRET. The jobs database holds only in-flight background work; restoring without it loses queued work but no durable records. Gateway in-flight reservations are reconstructed on restart.
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 or 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 any version-specific upgrade notes.
2. Run pnpm test:cf.
3. Export D1 metadata and usage-event databases.
4. Apply any required Data Catalog maintenance change.
5. Run pnpm release:build && pnpm release:check && pnpm release:publish.
6. Verify each deployment and the complete asynchronous evidence path.
7. Watch queue lag, D1 errors, warehouse writes, and R2 SQL reads through the rollout window.

Publishing does not initialize D1; run pnpm release:db-init --remote when the schema baseline must be applied to remote databases.

Rollback#

Application rollback changes code only; it does not restore the current initialization baseline or reverse changes to persistent stores. This development workflow provides no historical migration or cross-version compatibility guarantee. To recover a live environment:

1. Stop the new process or Worker deployment.
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#

Releases that need steps beyond this general guide carry notes in docs/upgrades/v<version>.md; these files are linked from the GitHub Release notes when they exist.

Release Independence#

Public Node releases and the Cloudflare demo deployment use isolated resource coordinates and are published independently. Never point one deployment at the other's database, queue, or bucket resources, and do not reuse generated IDs across environments.