Upgrades and Rollback

Upgrades and Rollback

Treat an upgrade as an application, schema, configuration, and operational change—even for a small version bump.

Before upgrading

1. Read release notes between the deployed and target versions.
2. Record the current version, image digest/commit, configuration, and health.
3. Run the repository deployment validation for source deployments.
4. Create a verified database backup outside the active volume.
5. Confirm rollback tooling and the previous image are available.
6. Choose a quiet window because the single writer may be briefly unavailable.

Upgrade acceptance

• Health endpoint succeeds.
• Exactly one dashboard writer is active.
• Database integrity and representative reads succeed.
• UI and WebSocket authenticate correctly.
• A controlled provider session is ingested.
• Prometheus scrapes and Grafana panels recover.
• Remote sources resume syncing.
• No unexpected migration or permission errors appear in logs.

Roll back for a clear reason

Rollback is appropriate when the new application is unhealthy, cannot ingest, has a severe UI/API regression, or violates the persistence contract. Preserve logs and a post-failure backup before changing state when safe.

The supported production helper backs up first:

./deployments/scripts/rollback.sh \
  --env production \
  --method helm \
  --namespace agent-monitor-production

Application rollback and database restore are separate decisions. Do not restore an older database merely because an older image is deployed; that discards newer history. Restore data only when compatibility or corruption analysis requires it.

Source and desktop upgrades

For source installs, keep local changes in source control and rebuild from a known commit. For packaged desktop apps, preserve the external app-data directory and verify the new bundle reads the existing history. Never delete data directories as a routine upgrade step.

Canonical commands: Deployment reference.