mediabox-bootstrap/migration/README.md

Plex Migration — Windows → Linux, nothing lost

✅ EXECUTED 2026-08-01 — M0 through M4 complete in one day

Plex is live on Linux with its original identity (eb69ec8a…), watch state intact, direct play verified with a real session. In soak (M5). This file is now the record of the procedure; deviations that a future re-run must know about:

1. VACUUM is mandatory after the remap. The no-backslash gate greps the raw DB file and hits deleted rows lingering on SQLite free pages. Plain sqlite3/python cannot open the DB (custom icu_root collation — do NOT fake it); run VACUUM with Plex's own SQLite via docker run --entrypoint.
2. Expect phantom rows from dead eras. 1,715 backslash rows survived the remap legitimately: Sync+ cache from old D:/E:/G: drive letters (+ orphan media_items), 6 rows for a dead \\tesla NAS, and 115 UNC blobs in download_queue_items.decision_result. All deleted; 3 real theme-music paths re-pathed. The remap itself was correct — these predate the current library roots.
3. Verify staged copies with rsync -an --delete --stats (0 transferred / 0 deleted), never du -sb equality — directory apparent sizes differ across filesystems.
4. First boot needs systemctl start --no-block in cloud-init runcmd — enable alone misses the boot it runs in (fixed in user-data).
5. Post-go-live, the Plex image pin was reversed (Mike, 2026-08-02): :latest + watchtower daily 05:00 with ntfy. Watchtower needs DOCKER_API_VERSION=1.44 against Engine 29.

Cleanup 2026-08-02: staging dir + .pre-remap/.pre-syncfix sidecars deleted. Rollback net = NAS media_pc backup + Plex's scheduled DB backups.

Supersedes the earlier "forward-only, fresh Plex" decision. That call was made before the library was measured. At 27 TB, 25,148 video items and 337 GB of already-generated preview cache, rebuilding fresh costs one to three weeks of saturated NAS link and permanently loses every manual match fix. Migration is the cheaper and lower-risk option.

Revised 2026-07-31: no Windows-side robocopy, D: itself is the backup until everything on it is copied to the NAS media_pc share from Linux, and the 337 GB Media/ cache lives on the 3 TB ext4 disk — not the SSD — from day one. D: is therefore formatted before Plex first starts, not after the soak.

What survives

Watch history and resume points across all items, play counts, ratings, collections, playlists, every manual match correction, poster and artwork choices, added-at dates (so Recently Added stays meaningful), the 337 GB preview cache, and the server identity — shared users stay invited, clients do not need to re-add the server, and there is no claim step at all.

Calibre (25.4 GB) and Nikola iPad (1.2 GB) also survive — they move to the NAS media_pc share. Nothing on D: is abandoned.

Plex's own article calls cross-OS moves "possible but not officially supported and not covered here." That is a documentation gap, not a technical barrier. The database is platform-independent; what Plex declines to help with is mapping the settings, which gen-preferences.ps1 does.

Facts everything below depends on

Source	PMS 1.43.3.10828, Windows 10, data dir D:\Plex\Local Data
Server identity	machineIdentifier eb69ec8a… — preserved, not regenerated
Data directory	~374 GB total → ~364 GB after pruning (~27 GB minus Media/)
Library	1,360 movies · 23,493 episodes · 295 other video · 20,798 audio
Path rows	80,126 media_parts · 14,837 media_streams · 11 → 9 roots
Target layout	DB + Metadata/ on the SSD · Media/ (337 GB) on the 3 TB ext4 disk
Backup	Full copy on NAS media_pc (write share), made from Linux before D: is formatted
NAS mounts	6 library shares read-only + media_pc read-write, at /mnt/nas/<exact share name>

---

M0 — Prepare, while Windows is still running

Disable automatic trash emptying first. The registry confirms autoEmptyTrash = 1. The new NAS account is read-only on the library shares, so Plex can no longer delete files — but a missing mount at scan time would still purge library records. Settings → Library → untick Empty trash automatically after every scan.

Generate the Linux settings file from the registry. Write it to D:, not C: — C: is the install target and gets wiped:

powershell -ExecutionPolicy Bypass -File .\gen-preferences.ps1 -Out D:\mbx\Preferences.xml
[xml](Get-Content -Raw D:\mbx\Preferences.xml) | Out-Null; 'XML OK'

Stop Plex Media Server completely — tray icon → Exit, then confirm no Plex Media Server.exe remains. This is the database's final clean shutdown; a copy taken mid-WAL is inconsistent and you will not find out until much later. Do not start Plex on Windows again after this.

There is no robocopy here. D: is untouched by the install and is the backup until M2 copies it off.

GATE M0 — D:\mbx\Preferences.xml exists, parses, and contains MachineIdentifier. Plex is fully exited.

---

M1 — Install Linux

Follow the main runbook.md phases 2–8 (BIOS — the iGPU toggle is mandatory, Quick Sync is the transcode device — then USB, install, first boot, NAS credentials and the seven mounts, shell-mcp cutover, vainfo). The autoinstall targets Disk 0 by serial 1808AE802176 and leaves the 3 TB disk untouched.

GATE M1 — runbook gates 4–8 all pass. In particular: all seven mounts [ok], the six library shares refuse writes, media_pc accepts them, and vainfo lists H.264/HEVC entrypoints.

---

M2 — Copy everything off D:

Mount the NTFS disk read-only and copy all of it to the NAS write share:

DEV=/dev/$(lsblk -dno NAME,SERIAL | awk '$2=="WD-WCC7K3JAEDR3"{print $1}')
sudo mkdir -p /mnt/dwin
sudo mount -t ntfs3 -o ro "${DEV}1" /mnt/dwin   # partition number per lsblk

# 1) Full PMS backup — excludes match the old robocopy list
sudo rsync -a --info=progress2 \
  --exclude='Cache/' --exclude='Codecs/' --exclude='Drivers/' \
  --exclude='Crash Reports/' --exclude='Logs/' --exclude='Updates/' \
  "/mnt/dwin/Plex/Local Data/Plex Media Server/" \
  "/mnt/nas/media_pc/backups/mediabox/PMS/"

# 2) The generated settings file
sudo rsync -a "/mnt/dwin/mbx/" "/mnt/nas/media_pc/backups/mediabox/mbx/"

# 3) Everything else worth keeping — nothing on D: is abandoned
sudo rsync -a --info=progress2 "/mnt/dwin/Calibre/"      "/mnt/nas/media_pc/Calibre/"
sudo rsync -a --info=progress2 "/mnt/dwin/Nikola iPad/"  "/mnt/nas/media_pc/Nikola iPad/"

Codecs and Drivers are Windows binaries — carrying them to Linux breaks transcoding. Cache is regenerable.

Expect this to take a long time — Metadata/ and Media/ are millions of small files, and small-file writes over CIFS are slow. Plan on hours, possibly overnight. It only has to happen once.

GATE M2 — rsync exits 0 on all four copies. Spot-check on the NAS that backups/mediabox/PMS/Plug-in Support/Databases/, Metadata/ and Media/ are present and that Calibre/ and Nikola iPad/ file counts look right. Do not proceed to M3 on a copy you have not listed.

Optional rehearsal: before M3, run migrate-db.sh on a scratch copy of the database from /mnt/dwin and start a throwaway Plex against it on an --internal Docker network (no internet, so it cannot collide with the server identity). Browse it and confirm counts and watch state. This proves the migration while D: is still intact.

---

M3 — Stage, format D:, place the data

Media/ cannot stay on the SSD (337 GB, Mike's call 2026-07-31) and cannot live on the NAS (network cost + RAID space on disposable cache). Its home is the 3 TB disk — which currently holds the source data. So: stage through the SSD, format, move.

# 1) Restore the config (everything EXCEPT Media/) to its real home on the SSD
sudo install -d -o 3000 -g 3000 /srv/plex/config
sudo rsync -a --info=progress2 --exclude='Media/' \
  "/mnt/dwin/Plex/Local Data/Plex Media Server/" \
  "/srv/plex/config/Library/Application Support/Plex Media Server/" \
  --exclude='Cache/' --exclude='Codecs/' --exclude='Drivers/' \
  --exclude='Crash Reports/' --exclude='Logs/' --exclude='Updates/'

sudo install -o 3000 -g 3000 -m 0644 /mnt/dwin/mbx/Preferences.xml \
  "/srv/plex/config/Library/Application Support/Plex Media Server/Preferences.xml"

# 2) Stage Media/ on the SSD — temporary, ~337 GB into ~400 GB free. Check first:
df -h /
sudo rsync -a --info=progress2 \
  "/mnt/dwin/Plex/Local Data/Plex Media Server/Media/" \
  /srv/plex-media-staging/

# 3) Unmount and format D: — BY SERIAL, never /dev/sdX
sudo umount /mnt/dwin
lsblk -o NAME,SERIAL,SIZE,FSTYPE
DEV=/dev/$(lsblk -dno NAME,SERIAL | awk '$2=="WD-WCC7K3JAEDR3"{print $1}')
echo "$DEV"                          # sanity-check this before continuing
sudo wipefs -a "$DEV"
sudo parted -s "$DEV" mklabel gpt mkpart primary ext4 0% 100%
sudo mkfs.ext4 -L mediabox-data "${DEV}1"
UUID=$(blkid -s UUID -o value "${DEV}1")
echo "UUID=$UUID /srv/data ext4 defaults,nofail 0 2" | sudo tee -a /etc/fstab
sudo mkdir -p /srv/data && sudo systemctl daemon-reload && sudo mount /srv/data

# 4) Move Media/ to its permanent home (fast local move, no NAS round trip)
sudo install -d -o 3000 -g 3000 /srv/data/plex-media
sudo rsync -a --info=progress2 --remove-source-files /srv/plex-media-staging/ /srv/data/plex-media/
sudo find /srv/plex-media-staging -type d -empty -delete
sudo chown -R 3000:3000 /srv/plex/config /srv/data/plex-media

The staging copy through the SSD is deliberate: local disk-to-disk at full SATA speed instead of a 337 GB round trip through gigabit CIFS. The NAS copy from M2 is the backup, not the restore source — unless something here fails, in which case it is exactly that.

GATE M3 — df -h /srv/data shows ~2.7 TB, survives a reboot. /srv/data/plex-media and the config tree are owned 3000:3000. The staging directory is gone and the SSD is back to mostly free.

---

M4 — Remap and first start

sudo /srv/mediabox-bootstrap/migration/migrate-db.sh \
  "/srv/plex/config/Library/Application Support/Plex Media Server/Plug-in Support/Databases/com.plexapp.plugins.library.db"

sudo RENDER_GID=$(stat -c '%g' /dev/dri/renderD128) \
  /srv/mediabox-bootstrap/scripts/50-plex.sh

migrate-db.sh keeps a .pre-remap rollback copy, asserts that no Windows paths remain, that the counts moved 1:1, that the "Dr. Korval" tag and the four Liaden book summaries are untouched, and finally stats 200 random remapped paths against the real filesystem.

As executed: the no-backslash gate additionally required deleting phantom Sync+ cache rows from dead drive-letter eras, 6 dead \\tesla rows and 115 download_queue_items UNC blobs, then VACUUM with Plex's own SQLite (see the banner at the top) before the raw-file grep came back clean.

No claim token. The server already has its identity. The compose bind-mounts /srv/data/plex-media over .../Plex Media Server/Media, so the migrated thumbnails are in place from the first start.

scripts/60-media-relocate.sh is no longer needed — Media/ is born on /srv/data. What still matters from it is the verification: after first start, force thumbnail generation on one title and confirm the write lands under /srv/data/plex-media — that is the EXDEV cross-filesystem question, which can only be tested, not reasoned about.

GATE M4 — migrate-db.sh exits 0 with 200/200 sampled files resolve on disk. plex.thewichersfamily.com loads and shows Magi Plex with Movies 1,360 and 23,493 episodes; watch history and Continue Watching intact; a remote client that already had this server still sees it without re-adding. Play something and confirm intel_gpu_top shows the video engine working. The one-title thumbnail test writes under /srv/data/plex-media.

---

M5 — Soak

One to two weeks. Confirm mounts survive a NAS reboot, the GPU survives a kernel update, and the box comes back unattended from a real power cut. That last one is the acceptance test for "headless".

Leave the NAS media_pc backup in place — it is the durable copy of the old server. Prune it later if the space is ever needed; that is a deliberate decision, not a cleanup step.

---

If something goes wrong

Before M3 step 3 (the format), D: is intact and everything is reversible on the data side — Windows itself is gone after M1, but a reinstall from the USB takes ~20 minutes and every copy still exists. After the format, the NAS media_pc backup is the recovery source: it outlives every step here. (The on-box .pre-remap/.pre-syncfix sidecars were deleted 2026-08-02 after the soak-start all-clear.)