docs(29): jellyfin 10.10.3 -> 10.11.8 + scyfin theme migration on dev
Documents: - Staged migration path (10.10.3 -> 10.10.7 -> 10.11.8). Direct skip is unsupported per jellyfin#15027/#15244/#15293/#15504. - Snapshots at /home/user/snapshots/. - Schema diffs (library.db consolidated into jellyfin.db, ffmpeg 7.1.3). - Theme swap: Cineplex v1.0.6 -> scyfin OLED (the only top-tier 10.11.x theme with active 10.11 branch + zero open compat bugs). - The 10.10.3 home-section bug (CustomPrefs write but no HomeSection row) is fixed in 10.11.8 when POST body includes a HomeSections array. Verified end-to-end with test user. - Outstanding work before promoting dev to prod. - Rollback procedure (EF Core migrations are forward-only).
This commit is contained in:
parent
0122de7041
commit
9f3483a87c
1 changed files with 153 additions and 0 deletions
153
docs/29-jellyfin-10.11-upgrade-and-scyfin-migration.md
Normal file
153
docs/29-jellyfin-10.11-upgrade-and-scyfin-migration.md
Normal file
|
|
@ -0,0 +1,153 @@
|
|||
# 29 — Jellyfin 10.11.8 upgrade + scyfin theme migration (dev)
|
||||
|
||||
Date: 2026-05-11
|
||||
Scope: `jellyfin-dev` (dev.arrflix.s8n.ru) only. Prod still on 10.10.3.
|
||||
Trigger: home-section bug in 10.10.3 — `POST /DisplayPreferences/usersettings?client=Jellyfin%20Web` updated `CustomPrefs` but did NOT insert into the `HomeSection` table. Web UI ignored the layout and rendered factory defaults including Next Up. Verified fixed on 10.11.8 — see § 5.
|
||||
|
||||
---
|
||||
|
||||
## 1. Migration path (executed)
|
||||
|
||||
```
|
||||
10.10.3 → 10.10.7 → snapshot → 10.11.8
|
||||
```
|
||||
|
||||
Direct 10.10.3 → 10.11.x is unsupported. Skipping 10.10.7 is the most common cause of `MigrateLibraryDb` crashes (jellyfin#15027, #15244, #15293, #15504). Both stages take ~10s on our 176MB config.
|
||||
|
||||
### Snapshots kept
|
||||
|
||||
```
|
||||
/home/user/snapshots/jellyfin-dev-pre-1011-upgrade-20260511-033309.tar.zst (137M)
|
||||
/home/user/snapshots/jellyfin-dev-post-10107-20260511-033839.tar.zst (138M)
|
||||
```
|
||||
|
||||
Both produced via privileged Alpine + `tar --zstd` because userns-remap blocks tar from writing back to host bind paths (per `feedback_docker_sudo_bypass.md`).
|
||||
|
||||
### Compose change
|
||||
|
||||
```yaml
|
||||
# /opt/docker/jellyfin-dev/docker-compose.yml
|
||||
- image: jellyfin/jellyfin:10.10.3
|
||||
+ image: jellyfin/jellyfin:10.11.8
|
||||
```
|
||||
|
||||
No volume changes. No env-var changes. Same `user: "1000:1000"`, `userns_mode: "host"`, same index.html bind-mount path (`/jellyfin/jellyfin-web/index.html`).
|
||||
|
||||
---
|
||||
|
||||
## 2. Schema changes observed
|
||||
|
||||
- `library.db` consolidated into `jellyfin.db` (EF Core finalisation). Old DB removed.
|
||||
- New tables: `BaseItems`, `BaseItemImageInfos`, `BaseItemMetadataFields`, `BaseItemProviders`, `BaseItemTrailerTypes`, `ItemValuesMap`, `MediaStreamInfos`, `AttachmentStreamInfos`, `KeyframeData`, `PeopleBaseItemMap`, `Peoples`. (Old `TypedBaseItems`, `mediastreams`, `People` are gone.)
|
||||
- `DisplayPreferences` + `HomeSection` schema unchanged — same columns as 10.10.3.
|
||||
- ffmpeg bumped 7.0.2 → 7.1.3 (better tonemapping).
|
||||
|
||||
Internal migrations applied automatically:
|
||||
```
|
||||
20251009200000_CleanMusicArtist
|
||||
20260206200000_FixLibrarySubtitleDownloadLanguages
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Theme switch — Cineplex v1.0.6 → scyfin OLED
|
||||
|
||||
Reasons:
|
||||
- Cineplex pinned to 10.10.x, abandoned for 10.11.
|
||||
- scyfin (https://github.com/loof2736/scyfin) is the only top-tier 10.11.x theme with a dedicated 10.11 branch + recent release (v1.5.3, 2026-03-25) + zero open 10.11 bug reports.
|
||||
- OLED variant gives a true black palette aligned with full-bleed ARRFLIX backdrop goals.
|
||||
|
||||
Imports:
|
||||
```css
|
||||
@import url('https://cdn.jsdelivr.net/gh/loof2736/scyfin@latest/CSS/scyfin-theme.css');
|
||||
@import url('https://cdn.jsdelivr.net/gh/loof2736/scyfin@latest/CSS/theme-oled.css');
|
||||
```
|
||||
|
||||
Plus ARRFLIX-specific overrides (accent `#E50914`, force-English Play button, hide Cast & Crew / Quick Connect / Cast / SyncPlay, themed scrollbar). Full CustomCss in `/tmp/dev-branding.json` and applied via:
|
||||
|
||||
```bash
|
||||
curl -X POST -H "X-Emby-Token: $TOK" -H "Content-Type: application/json" \
|
||||
--data-binary @branding.json \
|
||||
https://dev.arrflix.s8n.ru/System/Configuration/branding
|
||||
```
|
||||
|
||||
(POST returned 500 but the write persisted — verified via GET. Likely an EphemeralXmlRepository warning side-effect; non-blocking.)
|
||||
|
||||
---
|
||||
|
||||
## 4. Home-section bug — fixed in 10.11.8
|
||||
|
||||
The 10.10.3 bug: posting CustomCss-style `homesection0…9` keys updated `CustomPrefs` but did NOT insert into the `HomeSection` table. The web client (10.10 + 10.11) reads `HomeSection` rows for `client="Jellyfin Web"`, so the legacy POST was a no-op visually.
|
||||
|
||||
On 10.11.8 the same endpoint accepts a `HomeSections` array in the request body and writes both `CustomPrefs` and `HomeSection` rows atomically. Tested:
|
||||
|
||||
```bash
|
||||
curl -X POST -H "X-Emby-Token: $TOK" -H "Content-Type: application/json" \
|
||||
"https://dev.arrflix.s8n.ru/DisplayPreferences/usersettings?userId=$UID&client=Jellyfin%20Web" \
|
||||
-d '{"Id":"","SortBy":"SortName",...,
|
||||
"CustomPrefs":{"homesection0":"resume","homesection1":"latestmedia", ...},
|
||||
"HomeSections":[{"Order":0,"Type":"Resume"},{"Order":1,"Type":"LatestMedia"},{"Order":2,"Type":"None"}, ...],
|
||||
"Client":"Jellyfin Web"}'
|
||||
```
|
||||
|
||||
→ HTTP 204 + DB shows `Type=4` at slot 0, `Type=6` at slot 1, `Type=0` everywhere else.
|
||||
|
||||
Type integer reference (`Jellyfin.Data.Enums.HomeSectionType`):
|
||||
```
|
||||
0 = None
|
||||
1 = SmallLibraryTiles
|
||||
2 = LibraryButtons
|
||||
3 = ActiveRecordings
|
||||
4 = Resume
|
||||
5 = ResumeAudio
|
||||
6 = LatestMedia
|
||||
7 = NextUp <-- explicitly excluded by ARRFLIX policy
|
||||
8 = LiveTv
|
||||
9 = ResumeBook
|
||||
```
|
||||
|
||||
ARRFLIX policy is now: **slot 0 = Resume, slot 1 = LatestMedia, slot 2-9 = None**. Continue Watching is always on, Next Up never.
|
||||
|
||||
---
|
||||
|
||||
## 5. Plugin compat
|
||||
|
||||
- OpenSubtitles **v20** (current prod) has `targetAbi: 10.9.0.0` — will NOT load on 10.11.x.
|
||||
- v24 with `targetAbi: 10.11.8.0` is required (jellyfin-plugin-opensubtitles#166).
|
||||
- Known regression: server issue #16544 reports SRT save failing on 10.11.7+ — workaround = Bazarr proxy. Re-test on dev before promoting to prod.
|
||||
|
||||
Plugin upgrade command (deferred until we validate the rest):
|
||||
```bash
|
||||
curl -X POST -H "X-Emby-Token: $TOK" \
|
||||
"https://dev.arrflix.s8n.ru/Packages/Installed/Open%20Subtitles?AssemblyGuid=4b9ed42f-5185-48b5-9803-6ff2989014c4&Version=24.0.0.0&RepositoryUrl=https%3A%2F%2Frepo.jellyfin.org%2Ffiles%2Fplugin%2Fmanifest.json"
|
||||
docker restart jellyfin-dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Outstanding before promoting dev → prod
|
||||
|
||||
- [ ] Test scyfin OLED rendering across home / detail / playback / settings on dev.
|
||||
- [ ] Verify Continue Watching renders for `test` user (5 resume items present).
|
||||
- [ ] OpenSubtitles v24 install + smoke test on a Polish-audio episode.
|
||||
- [ ] Re-test HW accel — ffmpeg 7.1.3 changed tonemap; verify 4K HDR R&M still transcodes.
|
||||
- [ ] Update prod compose to `jellyfin/jellyfin:10.10.7` → snapshot → `10.11.8`.
|
||||
- [ ] Re-run `bin/set-home-layout.py` against prod once on 10.11.8 — should now work via API alone, no DB hack needed.
|
||||
- [ ] Retire `bin/fix-home-db.sh` from the canonical playbook (kept as emergency-only).
|
||||
|
||||
---
|
||||
|
||||
## 7. Rollback (if scyfin or any 10.11.8 behaviour blocks promotion)
|
||||
|
||||
EF Core migrations are forward-only — 10.10.3 will not start against a 10.11.x DB.
|
||||
|
||||
```bash
|
||||
docker stop jellyfin-dev
|
||||
docker run --rm --userns=host -v /home/docker:/dst alpine sh -c \
|
||||
"apk add --no-cache zstd tar; cd /dst; rm -rf jellyfin-dev/config; \
|
||||
tar -I 'zstd -d' -xf /dst/snap/jellyfin-dev-pre-1011-upgrade-*.tar.zst"
|
||||
sed -i 's|10.11.8|10.10.3|' /opt/docker/jellyfin-dev/docker-compose.yml
|
||||
docker compose -f /opt/docker/jellyfin-dev/docker-compose.yml up -d
|
||||
```
|
||||
|
||||
(Snapshot path is `/home/user/snapshots/`. Mount it into the alpine helper if needed.)
|
||||
Loading…
Reference in a new issue