From b2281dff5d4af0753d72d4d745736f2142b8ece5 Mon Sep 17 00:00:00 2001 From: jsboige Date: Fri, 19 Jun 2026 15:26:17 +0200 Subject: [PATCH] =?UTF-8?q?docs(dnn):=20#131=20DNN=20Phase=202=20exec=20+?= =?UTF-8?q?=20rollback=20runbook=20(9.11.1=E2=86=9210.3.2)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The DNN-side counterpart to the 2sxc migration plan (#543 Phase 1.5). Expands the one-line "Phase 2 — staging restore + schema analysis" named in #531 §4 into the DNN platform upgrade execution sequence + a 10.3.2-specific rollback runbook. - §1: preconditions — Phase 1.5 (2sxc) must be green first - §2: DNN execution sequence — single-jump 9.11→10.3.2 (per #531 §2.1, wizard handles schema directly), 4 steps (2.0 snapshot → 2.1 stage upgrade package → 2.2 apply files → 2.3 run wizard → 2.4 restart + smoke) - §3: intermediate validation gates — C (wizard completion, post-2.3) + D (smoke green, post-2.4, the #533 gate) - §4: 10.3.2-specific rollback runbook — two-anchor model (Step 1.5.0 = pre-everything, Step 2.0 = post-2sxc-21 pre-DNN), DB+webroot restore procedure, go/no-go criteria, stepping-stone fallback - §5: updated 10.3.2 phase map showing where Phase 2 slots in Complements #543 (2sxc), #522 §4 (generic wizard mechanics, 10.1.2- superseded), #527 §6 (generic DNN rollback) — references, not duplicates. Doc-only, non-gated. Execution GATED jsboige; visual PASS verdict = ai-01 + jsboige. No production system touched. Co-Authored-By: Claude Opus 4.6 --- .../131-dnn-phase2-exec-rollback.md | 224 ++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 docs/dnn-localization/131-dnn-phase2-exec-rollback.md diff --git a/docs/dnn-localization/131-dnn-phase2-exec-rollback.md b/docs/dnn-localization/131-dnn-phase2-exec-rollback.md new file mode 100644 index 00000000..21a4505c --- /dev/null +++ b/docs/dnn-localization/131-dnn-phase2-exec-rollback.md @@ -0,0 +1,224 @@ +# #131 — DNN Phase 2 Execution + Rollback Runbook (9.11.1 → 10.3.2, post-2sxc-21) + +**Issue:** [#131 — DNN platform upgrade (sandbox → prod)](https://github.com/ArgumentumGames/Argumentum/issues/131) +**Author:** Claude Code @ myia-po-2023 (worker) +**Date:** 2026-06-19 +**Base:** master `4dd3c6bd` +**Status:** **DOC / non-gated.** The **DNN platform upgrade execution sequence** (Phase 2 of the 10.3.2 path) **and its +rollback runbook**, expanding the one-line "Phase 2 — staging restore + schema analysis (#527)" that +[#531 §4](131-target-revision-10.3.2-full-upgrade.md) names but does not detail for the post-cliff path. This is the +**DNN-side** counterpart to the [2sxc migration plan #543](131-2sxc-migration-plan.md) (Phase 1.5). Execution stays +GATED — this is the plan; running it is jsboige's call. + +> **Relationship to the arc** (anti-dup): the *why* (cliff #6902, target 10.3.2, templates already Razor14) lives in +> [#531](131-target-revision-10.3.2-full-upgrade.md). The **2sxc upgrade sequence** (Phase 1.5, must complete first) +> lives in [#543](131-2sxc-migration-plan.md). The **generic DNN upgrade mechanics** + the **sandbox go/no-go per stage** +> live in [#522 §4-§6](131-step1-sandbox-upgrade-runbook.md) (target 10.1.2-superseded, but mechanics reusable). The +> **6-phase go-live + the DNN-phase rollback table** live in [#527 §5-§6](132-deployment-runbook.md). **This doc adds the +> how for the DNN execution after Phase 1.5 is green + a 10.3.2-specific rollback runbook** that the others only name. + +--- + +## 1. Preconditions — Phase 1.5 (2sxc) must be GREEN first + +The whole 10.3.2 path hinges on [#543 §1](131-2sxc-migration-plan.md): **2sxc 21.07 LTS is installed and verified on +DNN 9.11.1 BEFORE the DNN upgrade crosses 10.2.0.** Do not start Phase 2 (this doc) unless: + +- [ ] [Phase 1.5](131-2sxc-migration-plan.md) **gate B is green** — 2sxc 21 healthy on DNN 9.11.1. +- [ ] The **Step 1.5.0 master backup** exists, is checksum-verified, and passes `RESTORE VERIFYONLY` (the rollback + anchor reused in §4 below). +- [ ] The site is currently **DNN 9.11.1.19 + 2sxc 21.x** (the only safe pre-crossing state). + +If Phase 1.5 is not green, **stop** — proceeding would cross the cliff with a workaround-less 2sxc (the rejected +DNN-first order, #543 §1). + +--- + +## 2. The DNN execution sequence (Phase 2 — the platform upgrade) + +> ⚠️ **Honesty boundary:** the *generic* DNN upgrade-wizard mechanics below are the standard community-documented flow +> and are reused from [#522 §4](131-step1-sandbox-upgrade-runbook.md). The **authoritative steps must be confirmed +> against the official DNN upgrade guide** (`docs.dnncommunity.org` → Upgrading) before execution — the same caveat #522 +> §4 carries. Everything about *ordering, validation gates, and rollback* in §3/§4 here is arc-grounded and stands alone. + +### §2.1 Single-jump or stepping-stone? (the path question) + +[#531 §2.1](131-target-revision-10.3.2-full-upgrade.md) confirms the DNN upgrade wizard handles the schema migration +**9.11.1 → 10.3.2 directly** — the cliff is a 2sxc problem (now solved by Phase 1.5), **not** a DNN-schema problem. + +| Path | What | Verdict | +|------|------|---------| +| **Direct jump (chosen)** | Run the 10.3.2 Upgrade package wizard over 9.11.1. The wizard migrates schema 9.11→10.3 in one pass. | ✅ the documented path (#531 §2.1) | +| Stepping-stone via 9.13.9 | Upgrade 9.11→9.13.9 first, then 9.13.9→10.3.2. | ⚠️ "#531 §2.1: migration aid only" — optional, adds a step + a backup cycle for no CVE gain (9.13.x closes 0 CVEs) | + +**Decision: direct jump 9.11.1 → 10.3.2**, because the wizard supports it and the cliff is already neutralized by +Phase 1.5. Reserve the stepping-stone only if the direct wizard fails on this specific DB (fallback, §4). + +### §2.2 Execution steps (sandbox/staging first, then prod) + +Each step has a **validation gate**. Do not start the next until the current is green. + +#### Step 2.0 — Pre-execution snapshot (the Phase-2 rollback anchor) +- [ ] **Re-snapshot** the current state (DNN 9.11.1 + 2sxc 21) — files tar+checksum + `BACKUP DATABASE … WITH CHECKSUM` + + `RESTORE VERIFYONLY`. **Two copies, off-host.** This is distinct from the Step 1.5.0 backup: it captures the + **post-2sxc-upgrade, pre-DNN-upgrade** state, which is the cleanest rollback target if the DNN wizard fails. +- [ ] Record: DNN 9.11.1.19, 2sxc 21.x, `DotNetNuke.dll` FileVersion, `web.config` checksum. + +#### Step 2.1 — Download + stage the 10.3.2 Upgrade package +- [ ] Download the **Upgrade package** for 10.3.2 from the DNN community release archive — **not** the Install package + (Install is greenfield; Upgrade preserves the DB, #522 §4 step 2). +- [ ] **Verify** the package version is 10.3.2 (not 10.1.x — the superseded target). +- [ ] Stage on the sandbox/staging host; **do not apply yet**. + +#### Step 2.2 — Stop IIS, apply the Upgrade package files +- [ ] **Stop the IIS site** (sandbox: stop IIS Express :8090 / staging: stop the app pool) — frees file locks (#522 §4 step 3). +- [ ] Copy the Upgrade package's files/bin over the site root — **preserves** `web.config`, `App_Data`, `Portals`, + `DesktopModules`, `bin\ToSic.*` (2sxc 21 binaries stay in place, #522 §4 step 4). +- [ ] **Do NOT run the wizard yet** — files only at this step. + +#### Step 2.3 — Run the upgrade wizard (schema migration) +- [ ] Browse to `http://localhost:8090/Install/Upgrade.aspx` (sandbox) — the wizard auto-detects the version gap and + runs the **schema + data migration** 9.11.1 → 10.3.2 (#522 §4 step 5). +- [ ] Watch the upgrade log: schema migration + any **skipped/reported extension**. **No fatal expected**; flag any. +- [ ] **Validation gate C** (below, §3.1): wizard completes, log clean, site boots. If fatal → **rollback to Step 2.0 + snapshot** (§4). + +#### Step 2.4 — Restart, full smoke +- [ ] **Restart IIS** (full app-pool recycle) — DNN caches must clear post-schema-migration. +- [ ] Run the **[#533](131-step2-smoke-test-checklist.md) consolidated smoke gate** (§3 cliff check, §4 stock apps, + §5 Argumentum, §6 8-language surface, §7 commerce). +- [ ] **Validation gate D** (§3.2): smoke green. If red → rollback to Step 2.0 snapshot (§4). + +--- + +## 3. Intermediate validation gates (the go/no-go checkpoints) + +These are the **between-steps** checkpoints the dispatch asks for. Each is a hard gate. + +### §3.1 Gate C — wizard completion (post-Step 2.3) +The point: catch a failed schema migration **before** investing in the full smoke. +- [ ] Upgrade-wizard log: **no `FATAL`**, no skipped-extensions errors. +- [ ] `DotNetNuke.dll` FileVersion = **10.3.2.x** (the wizard applied the new binaries). +- [ ] Site **boots to the homepage** (no yellow-screen / no 500) — a boot failure here means the schema migration left + the DB inconsistent → rollback. +- [ ] 2sxc admin → System Info still reports **21.x** (the DNN upgrade did not regress 2sxc). + +### §3.2 Gate D — smoke green (post-Step 2.4) +The [#533](131-step2-smoke-test-checklist.md) gate, in full. The two 10.3.2-mandatory families: +- [ ] **§3 cliff check** — no `DnnJsInclude` IIS worker-process crash (the whole reason Phase 1.5 ran first; this confirms + the workaround held across the DNN upgrade). +- [ ] **§4 stock apps** — the 25 stock 2sxc apps load (v20 infra: `SexyContentWebPage` deprecation, module-path rename). +- [ ] **§5 Argumentum** — 4 custom templates still bind (pre-cleared Razor14, #531 §3). +- [ ] **§6 platform** — 8-language switcher, Admin/PersonaBar. +- [ ] **§7 commerce** — OpenStore + Stripe checkout path (the #445 decision window). + +**Gate D green → eligible for [#527](132-deployment-runbook.md) Phase 5 (prod go-live).** Gate D red → rollback (§4). + +--- + +## 4. Rollback runbook (10.3.2-specific) + +This complements [#527 §6](132-deployment-runbook.md) (DNN-phase rollback table, 10.1.2-oriented) and +[#543 §3](131-2sxc-migration-plan.md) (2sxc-specific rollback). The 10.3.2 path adds its own anchors: + +### §4.1 The rollback anchors (two distinct snapshots) + +| Anchor | Captured at | Contains | Use when | +|--------|-------------|----------|----------| +| **Step 1.5.0 backup** | before the 2sxc upgrade | DNN 9.11.1 + 2sxc **15.02** | full reset to the original pre-anything state | +| **Step 2.0 snapshot** (this doc) | after Phase 1.5 green, **before** the DNN upgrade | DNN 9.11.1 + 2sxc **21** | DNN wizard failed but 2sxc 21 was healthy — restores the 2sxc work without redoing Phase 1.5 | + +**Choose the right anchor:** if the DNN wizard fails, prefer the **Step 2.0 snapshot** (preserves the verified 2sxc 21 +upgrade). Use the **Step 1.5.0 backup** only if you want to reset everything (including redoing Phase 1.5). + +### §4.2 Rollback procedure (DB + webroot) + +``` +1. STOP the IIS site (free all file locks). +2. DB RESTORE: + ALTER DATABASE [DotNetNuke] SET SINGLE_USER WITH ROLLBACK IMMEDIATE; + RESTORE DATABASE [DotNetNuke] + FROM DISK = '…\.bak' + WITH REPLACE, RECOVERY, CHECKSUM; + -- VERIFYONLY first, always (the rollback contract, #527 §6): + RESTORE VERIFYONLY FROM DISK = '…\.bak' WITH CHECKSUM; +3. WEBROOT RESTORE: + - delete the upgraded webroot's bin/ + the wizard-touched files + - restore bin/, web.config, Portals/, DesktopModules/, App_Data/ from the anchor's files backup + - verify file count + checksums match the anchor manifest +4. START the IIS site; confirm it boots to DNN + 2sxc . +5. Record the rollback in the deploy log (timestamp, anchor used, reason). +``` + +> ⚠️ **Honesty boundary:** the exact DB name / connection string is **prod-only** (sanitized in repo, #527 §3). The SQL +> shape above is the standard SQL Server restore; confirm against the real prod instance at execution. + +### §4.3 Go/no-go criteria for rollback + +Roll back immediately if **any** of: +- Gate C red (wizard fatal / boot failure post-schema-migration). +- Gate D §3 red — a `DnnJsInclude` win32 crash appears (means the 2sxc workaround did not survive the DNN upgrade — + serious; rollback + re-verify Phase 1.5). +- Gate D §7 red AND #445 is undecided (commerce failure blocks prod, #533 §9). +- The rollback path itself is **not verified** (`RESTORE VERIFYONLY` on the anchor must be green **before** starting + Step 2.2 — the rollback contract). + +**Do NOT roll back silently:** every rollback is a deploy-log event + an ai-01 + jsboige notification (the worker signals, +does not decide, #533 §1). + +### §4.4 The "wizard failed, what now" branch + +If the direct 9.11→10.3.2 wizard fails (gate C red) on this specific DB: +1. Roll back to the **Step 2.0 snapshot** (DNN 9.11.1 + 2sxc 21). +2. **Try the stepping-stone** ([#531 §2.1](131-target-revision-10.3.2-full-upgrade.md) "migration aid"): upgrade + 9.11→9.13.9 first, then 9.13.9→10.3.2. Two wizard passes, two backup cycles. +3. If the stepping-stone also fails → **escalate to jsboige**; the DB may have a customization the wizard cannot migrate. + This is the §7 honesty-boundary item (real prod schema is prod-only). + +--- + +## 5. Where this slots in (the 10.3.2 phase map, updated) + +Consolidated view — Phase 2 (this doc) is the DNN execution after Phase 1.5 (2sxc) is green: + +``` +Phase 0 pre-flight (#527) +Phase 1 prod backup files+DB (#527) ← the master anchor +Phase 1.5 2sxc 15.02 → 21.07 LTS on DNN 9.11.1 ← #543 (gates A+B) +Phase 2 DNN 9.11.1 → 10.3.2 + rollback ← THIS DOC (§2 exec, §3 gates C+D, §4 rollback) +Phase 3 migration plan incl. 2sxc content-types (#531 §4 expanded) +Phase 4 sandbox test on prod-restored data (#527) + cliff smoke (#533 §3/§4) + 25-app verify +Phase 5 prod go-live (#527) +Phase 6 rollback strategy (#527 §6 + #543 §3 + §4 here) +``` + +**Hard gate:** Phase 2 (this doc) requires Phase 1.5 green. Phase 5 (prod go-live) requires Phase 2 gate D green. + +--- + +## 6. Gate boundaries (this document) + +- ✅ Details the DNN execution sequence (single-jump 9.11→10.3.2, post-2sxc-21) with 4 steps + 2 validation gates. +- ✅ Adds a **10.3.2-specific rollback runbook** (two-anchor model, DB+webroot restore procedure, go/no-go criteria, + stepping-stone fallback) — complements #527 §6 (generic DNN) and #543 §3 (2sxc). +- ✅ Documents the **intermediate validation gates** (C: wizard completion, D: smoke green) the dispatch asks for. +- ❌ Does **not** execute anything — DNN upgrade, wizard, DB restore are all GATED jsboige. +- ❌ Does **not** duplicate the 2sxc upgrade sequence (#543), the generic wizard mechanics (#522 §4), the cliff rationale + (#531/#520), the v20 breaking-changes inventory (#511 §6), or the smoke-test gate (#533) — references them. +- ❌ Does **not** decide #445 (Stripe) — flags §3.2 Gate D §7 as the window. +- ❌ Does **not** declare a QA verdict (ai-01 + jsboige only). + +## Sources + +- [131-target-revision-10.3.2-full-upgrade.md](131-target-revision-10.3.2-full-upgrade.md) (#531) — §2.1 single-jump path (wizard handles 9.11→10.3.2 directly), §2.2 2sxc upgrade path, §3 templates already Razor14, §4 Phase 2 expansion. +- [131-2sxc-migration-plan.md](131-2sxc-migration-plan.md) (#543) — Phase 1.5 (2sxc, must be green first), §1 2sxc-first ordering, §3 2sxc-specific rollback (complemented by §4 here). +- [131-step1-sandbox-upgrade-runbook.md](131-step1-sandbox-upgrade-runbook.md) (#522) — §4 generic wizard mechanics (reused), §5 risk register, §6 go/no-go per stage. +- [131-step2-smoke-test-checklist.md](131-step2-smoke-test-checklist.md) (#533) — §3 cliff check, §4 stock apps, §5 Argumentum, §6 8-language, §7 commerce — the Gate D smoke. +- [132-deployment-runbook.md](132-deployment-runbook.md) (#527) — §5 6-phase go-live, §6 DNN-phase rollback table (complemented by §4 here), Phase 1 backup = master anchor. +- [131-cve-correction-and-target-refinement.md](131-cve-correction-and-target-refinement.md) (#520) — §3 the cliff at 10.2.0 (issue #6902). +- ai-01 dispatch `msg-20260619T110913` — Phase 2 exec + rollback doc. + +--- + +*Worker Phase 2 execution + rollback runbook (doc/non-gated). The DNN upgrade execution is GATED jsboige; the visual +PASS verdict is ai-01 + jsboige. No production system touched.*