Skip to main content

Upgrade safely

Use this page when you need to apply an upgrade while keeping sequence, rollback posture, and postchecks explicit.

When to use this page​

  • You are performing a stack-wide or high-impact product upgrade.
  • You need the operational slice that sits on top of compatibility and release-note reading.
  • You need before-and-after verification tied to shared truth.

Prerequisites​

Architecture / Flow​

Step-by-step procedure​

1. Record the pre-upgrade baseline​

Use:

GET /api/v1/platform/services
GET /api/v1/observability/readiness

2. Compare repo truth and runtime truth before and after the change​

Use:

python ./scripts/verify_runtime_materialization.py --check

3. Keep rollback posture explicit before execution​

Define:

  • which product or layer moves first
  • what state counts as a failed intermediate step
  • what rollback boundary is safe

4. Execute the bounded owner-approved change​

If the chosen sequence requires stack redeploy:

bash ./scripts/redeploy-host-stack.sh

5. Run post-upgrade verification​

Re-run:

  • stack-health and readiness checks
  • runtime materialization verification
  • one representative user or operator path

Verification​

This runbook is being used correctly when:

  1. source and target versions are explicit
  2. rollback posture is defined before execution
  3. post-upgrade verification uses the same shared-truth surfaces as the baseline

Common failure modes​

Upgrading without a comparable baseline​

Problem:

  • postchecks have nothing concrete to compare against.

Better path:

  • capture services and readiness before the change

Continuing after an intermediate failure​

Problem:

  • later steps compound the inconsistency.

Better path:

  • stop at the failed boundary and recover before proceeding

Source Truth​

  • contracts/docs/public_manufacturer_docs_post_v1_runbooks_v1.json
  • JaddaHelpifyr/helpifyr-fabric:docs/operations/STACK_RECOVERY_RUNBOOK.md
  • JaddaHelpifyr/helpifyr-fabric:docs/testing/KNOWN_UPGRADE_RISKS.md
  • JaddaHelpifyr/jhf-deployment:docs/OPERATIONS.md

Next paths​