docs: capture Serenity majority migration plan

docs/planning/SERENITY_MAJORITY_MIGRATION_PLAN.md

@@ -0,0 +1,348 @@
+# Serenity Majority Migration Plan
+
+Status: approved planning baseline for the post-D7 Serenity drain strategy.
+
+Last updated: 2026-05-26
+
+## Goal
+
+Move the majority of remaining Docker workload off Serenity without recreating NFS/path-locality pain, while preserving the few roles that still legitimately need to live there until later infrastructure work is complete.
+
+This plan assumes:
+- qBittorrent and the torrent/media-locality lane stay on Serenity for now
+- PD is resource-constrained for a while, especially on RAM
+- `Wizarr` should be retired, not migrated
+- `Hawser` + `dockersocket` stay on Serenity because Dockhand uses them for remote management of Serenity's remaining Docker stacks
+- `Shelfmark` stays with the media-locality lane for now
+- Serenity's backup-DNS replacement should likely land on a small dedicated Raspberry Pi 4B rather than collapsing onto PD
+
+## Executive summary
+
+It is feasible to move the majority of Serenity's Docker workload off the box, but not as a single near-term wave.
+
+Right now the correct strategy is:
+1. retire obvious dead weight
+2. preserve the torrent/media-locality lane on Serenity
+3. keep Hawser/dockersocket, Newt, reranker, and backup-DNS as explicit temporary exceptions
+4. only move tiny low-risk apps early if PD headroom makes the move worth it
+5. do the real majority migration only after PD directly owns the relevant storage and path locality
+
+## Current placement decision matrix
+
+### Keep on Serenity now
+
+#### Media-locality lane
+- `GluetunVPN`
+- `qbit`
+- `qbit_manage`
+- `prowlarr`
+- `sonarr`
+- `sonarr-anime`
+- `radarr`
+- `lidarr`
+- `readarr`
+- `readarr-epub`
+- `bazarr`
+- `autobrr`
+- `unpackerr`
+- `shelfmark`
+
+Reason:
+- these either mount Serenity-owned `/mnt/user/data` directly or depend on workflows whose correctness currently assumes Serenity-local path ownership
+- splitting them early would turn this into an NFS-path rewrite project instead of a cleanup project
+
+#### Temporary intentional exceptions
+- `Hawser`
+- `dockersocket`
+- `Newt`
+- `technitium-dns-pilot`
+- `reranker`
+- `netdata`
+
+Reason:
+- `Hawser` + `dockersocket` remain part of the current Dockhand remote-management path
+- `Newt` still matters because Pangolin tunnels Serenity resources through Serenity-local Newt
+- `technitium-dns-pilot` preserves an off-PD DNS failure domain until replacement exists
+- `reranker` is not urgent to move while PD remains constrained
+- `netdata` is host-local monitoring; evaluate whether to simplify it later, not as a forced migration target now
+
+### Retire
+- `Wizarr`
+
+Reason:
+- operator confirmed it is unused and disposable
+- if onboarding needs return later, it can be rebuilt cleanly instead of migrated
+
+### Optional tiny move candidate
+- `Notifiarr`
+
+Reason:
+- low storage-locality coupling
+- but not worth forcing while PD remains constrained unless there is a concrete benefit
+
+## What should not be added to Serenity
+
+Default rule: add nothing new.
+
+Serenity is in a shrinking transitional role. New durable app responsibilities should go elsewhere unless they are explicitly temporary, host-local, and part of a migration or retirement aid.
+
+## Suggested long-term end state
+
+### PD long-term
+After storage cutover and capacity improvement, PD should absorb:
+- qBittorrent + Gluetun + qbit_manage
+- ARR family
+- `autobrr`
+- `unpackerr`
+- `shelfmark`
+- optional `Notifiarr`
+- `reranker` if PD remains the AI/control-plane center
+
+### Off-PD DNS resilience
+When Serenity retires, preserve at least one non-PD Technitium lane. Likely target:
+- dedicated Raspberry Pi 4B backup resolver
+
+### Serenity end state
+- no intentional durable production app role
+- no unique production dependency path left behind
+- host eligible for retirement after cooldown and verification
+
+## Execution-style Kanban board
+
+Use this as the working card map.
+
+### Epic A — Immediate cleanup and intention-locking
+
+#### A1. Retire Wizarr
+Status: ready
+Depends on: none
+
+Acceptance criteria:
+- `Wizarr` is removed from live Serenity runtime if still present
+- no reverse-proxy or bookmark expectation still points at it as a live service
+- docs no longer describe it as a migration target
+- rollback expectation is explicitly "rebuild if needed later," not "preserve migrated state"
+
+#### A2. Document Hawser + dockersocket as protected keepers
+Status: ready
+Depends on: none
+
+Acceptance criteria:
+- docs explicitly state Dockhand depends on `Hawser` + `dockersocket`
+- future cleanup cards do not treat them as accidental leftovers
+- any later rehome/removal must be paired with a replacement Dockhand management path
+
+#### A3. Decide whether netdata remains worth keeping
+Status: ready
+Depends on: none
+
+Acceptance criteria:
+- decision recorded as one of:
+  - keep as host-local monitoring until retirement
+  - simplify/replace with a lighter local signal
+  - remove after confirming broader monitoring already covers the operator need
+- if changed, verification includes equivalent host visibility from the replacement path
+
+### Epic B — Preserve Serenity's temporary intentional roles
+
+#### B1. Keep the media-locality lane stable on Serenity
+Status: locked
+Depends on: none
+
+Acceptance criteria:
+- no partial migration of qbit/ARR lane is attempted before storage design is ready
+- docs keep the lane grouped as an intentional temporary unit
+- future cards treat locality breakage as a rollback trigger, not a minor warning
+
+#### B2. Keep Hawser + dockersocket in place for Dockhand
+Status: locked
+Depends on: none
+
+Acceptance criteria:
+- `Hawser` and `dockersocket` remain healthy on Serenity
+- Dockhand remote management path still works for the remaining Serenity stacks
+- no proposal to move them is executed without a replacement management path
+
+#### B3. Keep Serenity-local Newt until Pangolin redesign exists
+Status: locked
+Depends on: none
+
+Acceptance criteria:
+- Pangolin-routed Serenity resources continue working
+- no retirement of Serenity-local Newt is attempted early
+- redesign work is handled as its own lane, not hidden inside app migration cards
+
+#### B4. Keep backup Technitium role on Serenity until replacement exists
+Status: locked
+Depends on: none
+
+Acceptance criteria:
+- off-PD DNS failure domain remains intact
+- no cutover collapses this role onto PD alone
+- replacement host is defined and verified before Serenity DNS role is removed
+
+#### B5. Keep reranker on Serenity until PD capacity or architecture changes
+Status: locked
+Depends on: none
+
+Acceptance criteria:
+- reranker remains stable where it is
+- no move is attempted just for neatness
+- any future move explicitly handles the live `/mnt/user/appdate/reranker` path oddity
+
+### Epic C — Optional tiny near-term moves
+
+#### C1. Re-evaluate Notifiarr against live PD headroom
+Status: ready
+Depends on: none
+
+Acceptance criteria:
+- current PD RAM/storage headroom is checked at execution time
+- clear recommendation recorded: move now, defer, or drop the idea
+- if moved, verification proves app health plus any expected integrations still work
+
+### Epic D — Replace Serenity special-case roles
+
+#### D1. Design the post-Serenity backup DNS lane
+Status: planned
+Depends on: none
+
+Target direction:
+- dedicated Raspberry Pi 4B backup resolver
+
+Acceptance criteria:
+- target host chosen and documented
+- role is explicitly outside PD's failure domain
+- expected sync, secrets, and verification model are documented before cutover
+
+#### D2. Build and validate the Pi 4B backup resolver
+Status: blocked
+Depends on: D1
+
+Acceptance criteria:
+- Pi 4B resolver is online and documented
+- sync path is defined
+- LAN clients can resolve through it as expected
+- it is clearly not dependent on PD for local authoritative continuity
+
+#### D3. Redesign Pangolin/Newt dependency
+Status: planned
+Depends on: none
+
+Acceptance criteria:
+- Serenity-hosted access path no longer requires Serenity-local Newt
+- replacement routing model is documented
+- cutover plan includes rollback and validation steps
+
+#### D4. Re-evaluate reranker final home
+Status: planned
+Depends on: none
+
+Acceptance criteria:
+- host choice made based on live resource reality and AI architecture, not symmetry
+- migration plan explicitly preserves existing data path and naming oddity handling
+
+### Epic E — Majority migration after storage ownership changes
+
+#### E1. Define PD storage cutover model
+Status: blocked
+Depends on: none
+
+Acceptance criteria:
+- exact target datasets/paths on PD are documented
+- ownership, mount semantics, and performance assumptions are explicit
+- migration no longer depends on NFS-style cross-host path fakery
+
+#### E2. Validate media/torrent path behavior on the target model
+Status: blocked
+Depends on: E1
+
+Acceptance criteria:
+- download path behavior validated
+- import path behavior validated
+- hardlink or equivalent behavior validated
+- post-processing behavior validated
+- ARR/qbit path mapping is internally consistent
+
+#### E3. Move qbit + Gluetun + qbit_manage
+Status: blocked
+Depends on: E2
+
+Acceptance criteria:
+- downloader lane works on the target without Serenity path dependence
+- VPN and management behavior are verified
+- rollback window is defined before source teardown
+
+#### E4. Move ARR + helper lane
+Status: blocked
+Depends on: E3
+
+Includes:
+- `prowlarr`
+- `sonarr`
+- `sonarr-anime`
+- `radarr`
+- `lidarr`
+- `readarr`
+- `readarr-epub`
+- `bazarr`
+- `autobrr`
+- `unpackerr`
+- `shelfmark`
+- optional `Notifiarr`
+
+Acceptance criteria:
+- libraries remain visible
+- imports and automation continue working
+- no stale Serenity-local path assumptions remain in configs
+
+#### E5. Post-cutover soak and verification
+Status: blocked
+Depends on: E4
+
+Acceptance criteria:
+- successful download/import verification exists
+- operator-facing health paths are normal
+- rollback confidence window passes without hidden path regressions
+
+### Epic F — Final Serenity retirement
+
+#### F1. Remove remaining special roles from Serenity
+Status: blocked
+Depends on: D2, D3, D4, E5
+
+Acceptance criteria:
+- no production path still depends on Serenity DNS role, Serenity-local Newt, or Serenity reranker placement
+- any retained backups are documented and off the critical path
+
+#### F2. Retire Serenity
+Status: blocked
+Depends on: F1
+
+Acceptance criteria:
+- no intentional production app remains
+- no unique resolver or tunnel role remains
+- docs describe Serenity as retired rather than transitional
+
+## Suggested execution order
+
+If only a few cards should move soon, use this order:
+1. A1 — Retire Wizarr
+2. A2 — Lock Hawser/dockersocket as intentional keepers
+3. A3 — Decide netdata end-state
+4. C1 — Re-evaluate Notifiarr only if there is real benefit
+5. D1/D2 — Create the replacement backup-DNS lane on Pi 4B
+6. D3/D4 — redesign special cases
+7. E1-E5 — execute the true majority migration only after PD storage ownership changes
+8. F1/F2 — retire Serenity
+
+## Recommendation
+
+Do not force a near-term "move the majority now" project.
+
+The correct near-term board is:
+- retire dead weight
+- keep the locality lane intact
+- keep Dockhand's Hawser path intact
+- build the future DNS replacement lane
+- wait for the storage and capacity conditions that make the real majority move sane