Upgrade Procedure¶
Applies to: All subscriptions
Purpose¶
Execute an upgrade in a defined order, with a clear point of no return and a verification gate before users are let back in.
Audience¶
System administrators and implementation engineers performing the upgrade.
Prerequisites¶
- Release notes read for every intervening version
- Rehearsed in a non-production environment at representative volume, and timed
- A verified backup, taken immediately before
- A maintenance window with headroom over the rehearsed time
- Users notified
- The rollback procedure to hand, and understood before starting
Steps¶
Phase 1 — preparation, before the window¶
| # | Step | Detail |
|---|---|---|
| 1.1 | Read every intervening release note | New configuration, migrations, breaking changes, deprecations |
| 1.2 | Record the current state | Application version, applied migrations, configuration snapshot |
| 1.3 | Rehearse | Non-production, representative volume, timed |
| 1.4 | Plan the window | Rehearsed time plus headroom for verification and rollback |
| 1.5 | Prepare new configuration | Any new settings the release requires |
| 1.6 | Notify users | Including the integration owners — ERPs will fail during the window |
Step 1.6 matters more than it looks. An ERP pushing documents into a stopped application will produce failures, and how it handles them is worth confirming beforehand.
Phase 2 — the window opens¶
| # | Step | Detail |
|---|---|---|
| 2.1 | Confirm no work is in flight | No jobs running, no bulk operation mid-way |
| 2.2 | Take a verified backup | The last easy point of return. Verify it, do not assume it |
| 2.3 | Stop the application | Cleanly |
| 2.4 | Stop the worker | Cleanly. A worker mid-task holds a lease |
| 2.5 | Confirm both are stopped | Not merely instructed to stop |
Phase 3 — apply the change¶
| # | Step | Detail |
|---|---|---|
| 3.1 | Apply migrations, in order | This is the point of no return |
| 3.2 | Verify each migration | Objects present; data migration counts cross-checked against storage metadata |
| 3.3 | Verify isolation policies | Present on any new table. A new tenant table without one is unprotected |
| 3.4 | Record what was applied | Your own per-environment migration log |
| 3.5 | Deploy application files | Preserve the environment configuration |
| 3.6 | Update dependencies | If the release requires it |
| 3.7 | Apply new configuration | From step 1.5 |
| 3.8 | Rebuild and publish the front end | It is compiled; a restart is not enough |
After step 3.1, rollback requires a database restore. Everything before it can be undone in minutes.
Step 3.3 is a five-minute check that prevents a genuine data-exposure defect, and it is the one most often skipped under time pressure.
Phase 4 — start and verify¶
| # | Step | Pass condition |
|---|---|---|
| 4.1 | Start the application | Starts; read the startup log to the end — no missing-object message |
| 4.2 | Start the worker | Running |
| 4.3 | Health check through the proxy | HTTP 200 |
| 4.4 | Sign in | Succeeds |
| 4.5 | Screens load with data | Present and correctly scoped |
| 4.6 | Cross-tenant check | A user of one registration cannot see another's |
| 4.7 | Background job | Submit one; it completes |
| 4.8 | Provider connection test | Succeeds |
| 4.9 | One document end to end | Ingest, register, print — in the sandbox |
| 4.10 | Integrations | Each ERP tested |
| 4.11 | Front end updated | New bundle served without a manual cache clear |
| 4.12 | Monitoring | Checks still passing and alerting |
If any check fails, do not release to users. Go to Rollback Procedure.
Phase 5 — release¶
| # | Step |
|---|---|
| 5.1 | Confirm every verification passed |
| 5.2 | Release to users |
| 5.3 | Notify integration owners to resume |
| 5.4 | Watch closely for the first hour |
| 5.5 | Record the upgrade: version, migrations, duration, issues |
| 5.6 | Retain the backup until the next successful cycle |
Phase 6 — the day after¶
| Check | Why |
|---|---|
| Overnight jobs completed | Scheduled work may use paths not exercised during verification |
| Rejection rate unchanged | A rise suggests behaviour changed |
| Integrations processed a full cycle | Some paths only run daily |
| No unexpected errors in the log | Quiet failures surface here |
| Users report nothing unusual | The final check |
Some problems only appear at month end. Keep the previous version's artefacts until a full cycle has passed.
Validation¶
| Check | Pass condition |
|---|---|
| Every phase-4 check passed | Before users were released |
| Migrations verified independently | Against storage metadata |
| Isolation confirmed | Cross-tenant test performed |
| End-to-end document processed | In the sandbox |
| Integrations tested | Each one, not assumed |
| Upgrade recorded | Version, migrations, duration |
| Backup retained | Until the next successful cycle |
Troubleshooting¶
| Symptom | Cause | Action |
|---|---|---|
| Will not start, naming an object | A migration was missed | Apply it and restart |
| Will not start, no schema message | Configuration lost or wrong | Restore the environment file |
| Starts, screens empty | Isolation or scope problem after migration | Do not disable policies. Verify scope and policy predicates |
| Cross-tenant check fails | A policy missing on a new table | Stop. Roll back. This is a data-exposure defect |
| Users see the old version | Front-end entry page cached | Set no-cache on the entry page |
| An integration fails after upgrade | A breaking change, or it uses application endpoints | Check the release notes |
| Window overran before verification | Migrations slower at real volume | Roll back rather than releasing unverified |
| Everything passes, problems next morning | Overnight or scheduled paths not exercised | Keep the day-after checks; retain the backup |