truenas-stacks/docs/planning/SERENITY_MAJORITY_MIGRATION_PLAN.md

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