# Serenity Majority Migration Plan

Status: approved planning baseline for the post-D7 Serenity drain strategy.

Last updated: 2026-05-26

## Execution update — 2026-05-26

Completed live:
- `Wizarr` retired from Serenity runtime
- stale Pangolin frontend for `wizarr.paccoco.com` disabled; public hostname now returns `404` instead of fronting a dead service
- `Hawser` + `dockersocket` verified live and healthy on Serenity
- `Notifiarr` re-evaluated against live PD headroom and intentionally left on Serenity for now
- `netdata` re-evaluated and kept on Serenity for now as host-local monitoring, not as an early migration target
- closeout check: no remaining open Serenity-specific Kanban cards exist from the completed cleanup/planning wave; only the documented planned/blocked future lanes remain

Current blockers verified live:
- PD is still RAM-constrained (`31 GiB total`, `27 GiB used`, `2.3 GiB free` at check time)
- PD still consumes Serenity storage over NFS (`/mnt/unraid/data` and `/mnt/unraid/immich` mounted from `10.5.30.5`)
- backup-DNS replacement is still only a target direction in docs; no Pi 4B resolver lane is live yet
- Serenity-local `Newt` is still part of the current Pangolin path for Serenity resources, so the special-case access lane is not retired yet

Interpretation:
- The no-regret cleanup phase is complete.
- The majority migration phase remains blocked on future infrastructure work, not on missed low-risk cleanup.

## 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: completed 2026-05-26
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: completed 2026-05-26
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: completed 2026-05-26
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: completed 2026-05-26
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