From 4e45be3577247f1d05a72f33f3908e34387b04b3 Mon Sep 17 00:00:00 2001 From: Sluijsens Date: Wed, 18 Nov 2026 08:17:02 +0100 Subject: [PATCH] Docs: volgorde voor uitrol van de mediabibliotheek naar productie (nog niet uitgevoerd) Co-Authored-By: Claude Sonnet 5.5 --- .../application-design/production-rollout.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 aidlc-docs/features/media-library/inception/application-design/production-rollout.md diff --git a/aidlc-docs/features/media-library/inception/application-design/production-rollout.md b/aidlc-docs/features/media-library/inception/application-design/production-rollout.md new file mode 100644 index 0000000..da9b6dd --- /dev/null +++ b/aidlc-docs/features/media-library/inception/application-design/production-rollout.md @@ -0,0 +1,29 @@ +# Media library: order of rollout to production + +Status (2026-11-18): NOT executed. Production only on an explicit go from Bryan. No `release/*` branches. Written on `feature/media-library-phase3c`. + +## Why the order matters + +The test sites went phase 2 -> copy -> 3b switch -> 3c. Production must take the same road, because the 3c release has **no copier and no switches** any more: `HeroImagesDropGuard` refuses to start the application (nothing is dropped) unless every photo of `HeroImages` is in `MediaAssets` (module `hero`) with the same hash, set and variants. A direct jump from today's production to 3c therefore fails at start-up, by design, unless `HeroImages` is empty. + +## Steps (each a separate release; every step: notice to SLS-Main, then Bryan's go) + +| # | Release | Settings | Check before the next step | Rollback | +|---|---|---|---|---| +| 0 | Fresh restore point of production (database dump + media directory listing, the Pi-Main script) and row counts: `HeroImages`, `HeroSlides`, `MediaAssets`, 10 sample public addresses | none | Restore point exists and its path is written down | n/a | +| 1 | Phase 2 (master after PR #27: write-through, crop per slide, read switch, 3a columns, `DropSlideImageForeignKey`) | `Media__Library__CopyOnStartup=true`, `Media__Library__DualWrite=true`; the other switches off | `GET media-library/read-check` says `matches: true` (hash, set and variants); public addresses unchanged | Switches off; `Down` of the additive migrations; last resort the restore point | +| 2 | Same build, setting only | `Media__Library__HeroPhotosInLibrary=true` (the guard refuses to start if the copy is incomplete; log says why) | Hero admin: upload, crop per slide, save, trash, restore; public site; read-check still matches. Leave it running for a quiet period (test had days) | Switch off: `HeroImages` is still a complete copy | +| 3 | Phase 3c (PR after #27): `DropHeroImagesTable` + guard; switches and copier removed | none needed (settings of step 1 and 2 are ignored; remove them from the environment file afterwards) | Journal: no guard error, `Applying migration ..._DropHeroImagesTable`, no failure; `HeroImages` gone; hero admin and site work | Only from the restore point of step 0 (take a NEW one right before this step): restore the dump, deploy the previous release. `Down` only recreates an empty table | + +Step 3 needs its own fresh restore point and Bryan's go on the exact migration (`DROP TABLE HeroImages`), as on test. + +## Things that differ from test + +- Production has real photos on both sites; test SlpSoftware had none (guard passes on an empty `HeroImages`). Count the photos per site in step 0 and compare them with `MediaAssets` after step 1. +- The workflow inputs for the switches exist only on the phase 2 build. After 3c they are gone, so steps 1 and 2 must be run while phase 2 is the latest release (do not merge PR 3c to master before step 2 is done on production). +- The new default `Media__AutoCleanupUnattached=false` applies from step 1: unused uploads are kept until someone deletes them in the library. +- The media directory is never changed destructively by these steps (retired sets stay for the retention time), so a database restore does not need a media restore. + +## Order of merging versus deploying to test + +Master deploys to test. After PR #27 (phase 2) is merged, test runs phase 2 code on databases where `HeroImages` is already dropped by 3c. With `Media__Library__HeroPhotosInLibrary=true` still in the environment file of test the photos are read from the library, but the legacy mirror (`HeroLegacyImageMirror`) then writes to `HeroImages`, which does not exist, so saving in the hero admin on test can fail until 3c is merged too. Merge #27 and the 3c PR directly after each other (or accept a short window on test where saving the hero fails).