Productie in een keer: de start kopieert HeroImages in de bibliotheek vlak voor de drop
Continuous Integration / config-asf (pull_request) Successful in 6s
Continuous Integration / config-sls (pull_request) Successful in 7s
Continuous Integration / changes (pull_request) Successful in 12s
Continuous Integration / frontend-prepare (pull_request) Skipped
Continuous Integration / frontend-build (pull_request) Skipped
Continuous Integration / frontend-test (pull_request) Skipped
Continuous Integration / frontend-lint (pull_request) Skipped
Continuous Integration / vulnerability-scan (pull_request) Successful in 1m12s
Continuous Integration / compile-sites (pull_request) Successful in 2m9s
Continuous Integration / backend-build (pull_request) Successful in 2m12s
Continuous Integration / backend-test (pull_request) Successful in 2m41s
Continuous Integration / publish-sls-test (pull_request) Skipped
Continuous Integration / publish-sls-production (pull_request) Skipped
Continuous Integration / deploy-sls-test (pull_request) Skipped
Continuous Integration / deploy-sls-production (pull_request) Skipped
Continuous Integration / publish-asf-test (pull_request) Skipped
Continuous Integration / deploy-asf-test (pull_request) Skipped
Continuous Integration / smoke-sls-test (pull_request) Skipped
Continuous Integration / smoke-asf-test (pull_request) Skipped

Een weigerende guard stopt de applicatie nu echt (ModuleStartupException wordt door de orchestrator doorgegooid).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-18 09:08:58 +01:00
co-authored by Claude Sonnet 5.5
parent 24f8ce1cc1
commit 370bd0dfd1
11 changed files with 249 additions and 26 deletions
@@ -1,29 +1,34 @@
# Media library: order of rollout to production
# Media library: rollout to production in one release
Status (2026-11-18): NOT executed. Production only on an explicit go from Bryan. No `release/*` branches. Written on `feature/media-library-phase3c`.
Status (2026-11-18): built on `feature/media-library-oneshot`, NOT executed, NOT on production. Production only on an explicit go from Bryan. No `release/*` branches.
## Why the order matters
## What changed compared with the staged plan
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.
Master (phases 2 and 3c) has no copier and no switches any more, so production (which still has the hero's photos only in `HeroImages`) could not go straight to it: the drop guard would refuse. The staged road (phase 2 with the copy, then 3b, then 3c) is no longer needed, because the start-up now does the copy itself, once, right before the drop:
## Steps (each a separate release; every step: notice to SLS-Main, then Bryan's go)
1. `HeroModule.UseModule` calls `HeroImagesDropGuard.PrepareAndVerify`. If the migration `DropHeroImagesTable` is pending:
2. the hero's own migrations up to the one before the drop are applied (so `HeroImages` has its final columns);
3. if `HeroImages` holds photos: the library tables are brought to the current schema through `IMediaLibrarySchema` (implemented by the Media module, which runs its migrations; this makes the order in which modules start irrelevant) and the photos are copied into `MediaAssets` (module `hero`): rows that differ are updated, missing rows inserted, nothing is deleted. HeroImages is the truth at that moment. The copy is one transaction;
4. `Verify` (unchanged, strict) compares hash, set hash and variants of every photo; on any difference it throws `ModuleStartupException`;
5. only then `Migrate()` runs the drop.
| # | 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 |
Uses (`MediaUses`) are not copied: after 3c nothing reads them (the library screen asks the modules' providers).
Step 3 needs its own fresh restore point and Bryan's go on the exact migration (`DROP TABLE HeroImages`), as on test.
**Guard now really stops the application.** `ModuleOrchestrator.UseModules` used to log every module exception and continue, so a refusing guard would have left the application running without the hero's migration (data safe, but a half-state). `ModuleStartupException` is now rethrown, so the host does not start; the log has a Critical line with the reason.
## Things that differ from test
## The steps on production
- 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.
| # | Step | Check | Rollback |
|---|---|---|---|
| 0 | Fresh restore point of production (database dump; the Pi-Main script) and counts per site: `HeroImages` rows, `HeroSlides`, 10 sample public addresses | Path of the restore point written down | n/a |
| 1 | Deploy this release (the one with the one-shot copy). Needs Bryan's go on the exact migration (`DROP TABLE HeroImages` after the copy) | Journal: `Applying migration ..._AddHeroPhotoColumns` (Media), the Hero migrations, `..._DropHeroImagesTable`, no Critical line; `/health` 200; `MediaAssets` has the same number of hero rows as `HeroImages` had; hero admin and public site; the 10 addresses unchanged | Restore point of step 0 + deploy the previous release. `Down` of the drop only recreates an empty table |
## Order of merging versus deploying to test
The restore point is the only way back after the drop. It must be taken immediately before step 1.
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).
## Things to know
- Both sites are handled the same way; a site with an empty `HeroImages` just migrates.
- If the guard refuses (Critical line, application not running): nothing was dropped (the copy is a transaction and the drop never ran). Fix the cause named in the message and start again; or deploy the previous release, which still reads `HeroImages`... only if the Hero migrations before the drop are compatible: those migrations (crop columns on slides, foreign key removal) are additive and the previous release ignores them, except that the foreign key `FK_HeroSlides_HeroImages_ImageId` is gone (the old release works without it).
- Media files are never touched by any of this.
- `Media__AutoCleanupUnattached` is off by default (unused uploads stay until deleted in the library).
- Test already ran the staged road; the one-shot path is tested on MariaDB in `HeroPhotosInLibraryTableTests.One_release_from_the_old_state_...` (hero tables just before phase 2, photos incl. a trashed one, no library tables) and should be tried on test once before production (restore the test database to a state before phase 2 if Bryan wants a rehearsal).