thethreemagi/mediabox-bootstrap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

migration: new sequence — D: is the backup, copy-off to media_pc, format before first start

Browse Source 
No Windows-side robocopy. Everything on D: (PMS dir, Calibre, Nikola
iPad) is copied to the NAS media_pc share from Linux, Media/ staged via
the SSD, D: formatted ext4 BEFORE Plex first starts, thumbnails live on
/srv/data. Fixes the M3 restore path that pointed at the unmounted
Share. Per Mike 2026-07-31.
This commit is contained in:
thethreemagi
2026-07-31 19:35:52 +01:00
parent 579787c8db
commit bc1e3d78d3
1 changed files with 163 additions and 123 deletions
Download Patch File Download Diff File Expand all files Collapse all files
migration/README.md
+163 -123
View File
@@ -6,6 +6,12 @@ already-generated preview cache**, rebuilding fresh costs one to three weeks of
saturated NAS link and permanently loses every manual match fix. Migration is saturated NAS link and permanently loses every manual match fix. Migration is
the cheaper and lower-risk option. 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 ## What survives
Watch history and resume points across all items, play counts, ratings, Watch history and resume points across all items, play counts, ratings,
@@ -14,6 +20,9 @@ choices, added-at dates (so Recently Added stays meaningful), the 337 GB
preview cache, and **the server identity** — shared users stay invited, clients 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. 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 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. 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 The database is platform-independent; what Plex declines to help with is
@@ -25,176 +34,207 @@ mapping the settings, which `gen-preferences.ps1` does.
|---|---| |---|---|
| Source | PMS **1.43.3.10828**, Windows 10, data dir `D:\Plex\Local Data` | | Source | PMS **1.43.3.10828**, Windows 10, data dir `D:\Plex\Local Data` |
| Server identity | `machineIdentifier eb69ec8a…` — preserved, not regenerated | | Server identity | `machineIdentifier eb69ec8a…` — preserved, not regenerated |
| Data directory | ~374 GB total → ~364 GB after pruning | | 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 | | 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 | | Path rows | 80,126 `media_parts` · 14,837 `media_streams` · 11 → 9 roots |
| Target layout | Whole data dir on the 500 GB SSD (~75 GB free) | | Target layout | DB + `Metadata/` on the SSD · `Media/` (337 GB) on the 3 TB ext4 disk |
| NAS mounts | 6 shares at `/mnt/nas/<exact share name>` | | 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 ## M0 — Prepare, while Windows is still running
**Disable automatic trash emptying first.** This is step 1 of Plex's own **Disable automatic trash emptying first.** The registry confirms
procedure and it matters more here than usual: the registry confirms `autoEmptyTrash = 1`. The new NAS account is read-only on the library shares,
`autoEmptyTrash = 1`, and the new NAS account is read-write. A missing mount at so Plex can no longer delete *files* — but a missing mount at scan time would
scan time would mean Plex deletes library records it has permission to delete. still purge library *records*. Settings → Library → untick *Empty trash
Settings → Library → untick *Empty trash automatically after every scan*. automatically after every scan*.
Generate the Linux settings file from the registry: Generate the Linux settings file from the registry. **Write it to `D:`, not
`C:` — `C:` is the install target and gets wiped:**
```powershell ```powershell
powershell -ExecutionPolicy Bypass -File .\gen-preferences.ps1 -Out C:\mbx\Preferences.xml powershell -ExecutionPolicy Bypass -File .\gen-preferences.ps1 -Out D:\mbx\Preferences.xml
[xml](Get-Content -Raw C:\mbx\Preferences.xml) | Out-Null; 'XML OK' [xml](Get-Content -Raw D:\mbx\Preferences.xml) | Out-Null; 'XML OK'
``` ```
**Stop Plex Media Server completely** — tray icon → Exit, then confirm no **Stop Plex Media Server completely** — tray icon → Exit, then confirm no
`Plex Media Server.exe` remains. The database must not be open when copied, or `Plex Media Server.exe` remains. This is the database's final clean shutdown;
the WAL will be mid-flight and the copy inconsistent. 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.
Copy the data directory to the NAS. Skip what must not travel: There is **no robocopy here**. `D:` is untouched by the install and is the
backup until M2 copies it off.
```powershell > **GATE M0** — `D:\mbx\Preferences.xml` exists, parses, and contains
robocopy "D:\Plex\Local Data\Plex Media Server" "\\korval\Share\backups\mediabox\PMS" ` > `MachineIdentifier`. Plex is fully exited.
/E /COPY:DAT /R:2 /W:5 /MT:16 `
/XD "Cache" "Codecs" "Drivers" "Crash Reports" "Logs" "Updates" `
/LOG:C:\mbx\pms-copy.log /TEE
```
`Codecs` and `Drivers` are **Windows binaries** — copying them to Linux breaks
transcoding. `Cache` is regenerable. Excluding them also trims the copy.
> **GATE M0** — robocopy reports 0 failures. `Plug-in Support\Databases\`,
> `Metadata\` and `Media\` are all present on the NAS. **Do not proceed on a
> copy you have not listed.**
--- ---
## M1 — Dry run, before anything is destroyed ## M1 — Install Linux
The whole migration can be rehearsed while Windows still works. This is the Follow the main `runbook.md` phases 2–8 (BIOS — the iGPU toggle is mandatory,
step that makes the rest safe. Quick Sync is the transcode device — then USB, install, first boot, NAS
credentials and the seven mounts, shell-mcp cutover, `vainfo`). The
On arrsstack (or any Linux host with the NAS mounted), take **only** the
database and Preferences — a couple of GB, not 364 — and run the remap:
```bash
sudo ./migrate-db.sh /path/to/copy/com.plexapp.plugins.library.db
```
Then start a throwaway Plex against it **with no internet access**, so it
cannot contact plex.tv and collide with the live server that shares its
identity:
```bash
docker network create --internal plex-dryrun
docker run --rm -d --name plex-dryrun --network plex-dryrun \
-v /path/to/dryrun-config:/config \
-v "/mnt/nas/media:/mnt/nas/media:ro" \
lscr.io/linuxserver/plex:latest
```
> **GATE M1** — browse the unclaimed server directly and confirm: Movies shows
> **1,360**, TV Shows shows **23,493 episodes**, watch state and resume points
> are present, and a title's file path resolves. If this passes, the migration
> is proven. If it fails you have lost an afternoon and nothing else.
---
## M2 — Install Linux
Follow the main `runbook.md` phases 2–5 (BIOS, USB, install, first boot). The
autoinstall targets Disk 0 by serial `1808AE802176` and leaves the 3 TB disk autoinstall targets Disk 0 by serial `1808AE802176` and leaves the 3 TB disk
untouched. untouched.
Write the NAS credentials and bring up the six mounts: > **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
```bash > `vainfo` lists H.264/HEVC entrypoints.
printf 'username=mediabox\npassword=<pass>\ndomain=WORKGROUP\n' \
| sudo tee /etc/cifs/korval.cred >/dev/null
sudo chmod 600 /etc/cifs/korval.cred
sudo systemctl daemon-reload
sudo /srv/mediabox-bootstrap/scripts/20-cifs.sh --verify
```
> **GATE M2** — all six mounts report `[ok]`, and `stat -c '%u:%g' /mnt/nas/media`
> returns `3000:3000`. Wrong ownership means Plex hits permission errors on
> every file.
--- ---
## M3 — Restore and remap ## M2 — Copy everything off `D:`
Mount the NTFS disk read-only and copy all of it to the NAS write share:
```bash ```bash
sudo install -d -o 3000 -g 3000 /srv/plex/config DEV=/dev/$(lsblk -dno NAME,SERIAL | awk '$2=="WD-WCC7K3JAEDR3"{print $1}')
sudo rsync -a --info=progress2 \ sudo mkdir -p /mnt/dwin
"/mnt/nas/Share/backups/mediabox/PMS/" \ sudo mount -t ntfs3 -o ro "${DEV}1" /mnt/dwin # partition number per lsblk
"/srv/plex/config/Library/Application Support/Plex Media Server/"
sudo install -o 3000 -g 3000 -m 0644 /path/to/Preferences.xml \ # 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.
```bash
# 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" "/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
```bash
sudo /srv/mediabox-bootstrap/migration/migrate-db.sh \ 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" "/srv/plex/config/Library/Application Support/Plex Media Server/Plug-in Support/Databases/com.plexapp.plugins.library.db"
sudo chown -R 3000:3000 /srv/plex/config
```
`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.
> **GATE M3** — `migrate-db.sh` exits 0 with the sample check reporting
> `200/200 sampled files resolve on disk`. That last line is the one that
> matters; SQL running without error proves nothing.
---
## M4 — First start
```bash
sudo RENDER_GID=$(stat -c '%g' /dev/dri/renderD128) \ sudo RENDER_GID=$(stat -c '%g' /dev/dri/renderD128) \
/srv/mediabox-bootstrap/scripts/50-plex.sh /srv/mediabox-bootstrap/scripts/50-plex.sh
``` ```
No claim token. The server already has its identity. `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.
> **GATE M4** — `plex.thewichersfamily.com` loads and shows *Magi Plex* with No claim token. The server already has its identity. The compose bind-mounts
> your libraries. Watch history and Continue Watching are intact. A remote `/srv/data/plex-media` over `.../Plex Media Server/Media`, so the migrated
> client that already had this server still sees it without re-adding. 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. > 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 ## M5 — Soak
One to two weeks on the supported layout. Confirm mounts survive a NAS reboot, One to two weeks. Confirm mounts survive a NAS reboot, the GPU survives a
the GPU survives a kernel update, and the box comes back **unattended** from a kernel update, and the box comes back **unattended** from a real power cut.
real power cut. That last one is the acceptance test for "headless". 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
## M6 — Relocate the preview cache (optional, post-soak) decision, not a cleanup step.
Only after M5. Moves the 337 GB `Media/` directory to the 3 TB ext4 disk so
future thumbnail growth (~28 MB per content-hour) stops consuming the SSD.
```bash
sudo /srv/mediabox-bootstrap/scripts/60-media-relocate.sh
```
Plex does **not** support relocating this directory. The script performs the
move, enables the bind mount, and then forces thumbnail generation on a single
title to prove writes succeed across the filesystem boundary — the one failure
mode that cannot be reasoned about, only tested. Rollback is moving it back.
--- ---
## If something goes wrong ## If something goes wrong
Before M2, everything is reversible — Windows still boots. After M2 the Before M3 step 3 (the format), `D:` is intact and everything is reversible on
recovery path is *reinstall*, not *roll back*: the USB rebuilds the box in the data side — Windows itself is gone after M1, but a reinstall from the USB
about twenty minutes and the data directory is still on the NAS. The database takes ~20 minutes and every copy still exists. After the format, the NAS
copy on the NAS outlives every step here, and `migrate-db.sh` leaves a `media_pc` backup is the recovery source: it outlives every step here, and
`.pre-remap` copy beside every database it touches. `migrate-db.sh` leaves a `.pre-remap` copy beside every database it touches.