The README and fork notes still described upstream and a pre-10.11 snapshot, so there was nothing accurate to hand an operator setting this up. - rewrite the README as an HA setup and configuration guide - add architecture, contributing and transcoding design notes - rewrite FORK-DIFF.md against the v12.0 base
5.8 KiB
Fork Diff: unkin/jellyfin-ha-src vs jellyfin/jellyfin
Base:
v12.0(6c073e19ddf604b2369c638716164fdab4c952dc) Head:origin/mainSummary: 56 files added · 16 upstream files modified · 15 upstream files deleted
What changed and why
This fork adds a high-availability layer so Jellyfin can run as more than one replica against shared storage. The design principle: extend through dependency injection, touch as little upstream code as possible. No core media, library, auth or plugin logic is rewritten.
| Bucket | Files | Lines added |
|---|---|---|
HA contracts and models (MediaBrowser.Controller) |
8 | ~330 |
Redis implementations (Emby.Server.Implementations) |
2 | ~350 |
| PostgreSQL database provider | 6 | ~4,980 |
| SQLite to PostgreSQL migration tool | 6 | ~720 |
| Modified upstream files | 16 | ~420 |
| Tests | 14 | ~2,790 |
| Helm chart | 17 | ~1,370 |
| CI and container build | 3 | ~175 |
New components
Transcode session store
| File | Purpose |
|---|---|
MediaBrowser.Controller/MediaEncoding/ITranscodeSessionStore.cs |
DI contract for durable transcode and live stream session tracking |
MediaBrowser.Controller/MediaEncoding/TranscodeSession.cs |
Session record: owning pod, lease expiry, manifest and segment paths, last durable segment |
MediaBrowser.Controller/MediaEncoding/LiveStreamSession.cs |
Record of an open live stream and the pod holding it |
MediaBrowser.Controller/MediaEncoding/TranscodeStoreOptions.cs |
RedisConnectionString and LeaseDurationSeconds |
MediaBrowser.Controller/MediaEncoding/NullTranscodeSessionStore.cs |
No-op store used when no Redis connection is configured |
Emby.Server.Implementations/MediaEncoding/RedisTranscodeSessionStore.cs |
Redis store; sessions under jellyfin:transcode:{playSessionId}, live streams under jellyfin:livestream:{liveStreamId}:{sessionId}, key TTL mirrors the lease |
Lease takeover runs as a single Lua script, so concurrent pods cannot both claim an expired lease:
local raw = redis.call('GET', KEYS[1])
if not raw then return 0 end
local session = cjson.decode(raw)
if session['LeaseExpiresUtc'] > tonumber(ARGV[1]) then return 0 end
session['OwnerPod'] = ARGV[2]
-- update expiry and SET with PX in the same script
return 1
Scan-leader lease
| File | Purpose |
|---|---|
MediaBrowser.Controller/ScheduledTasks/IScanLeaderLease.cs |
DI contract for the leader lease |
MediaBrowser.Controller/ScheduledTasks/ScanLeaderOptions.cs |
Enabled, LeaseDurationSeconds, GatedTaskKeys |
MediaBrowser.Controller/ScheduledTasks/NullScanLeaderLease.cs |
Always-leader default, preserving single-instance behaviour |
Emby.Server.Implementations/ScheduledTasks/RedisScanLeaderLease.cs |
Redis TTL lease; an unreachable Redis is treated as holding the lease |
Gated by default: RefreshLibrary, RefreshPeople, RefreshChapterImages,
AudioNormalization, TaskExtractMediaSegments, KeyframeExtraction,
CleanupUserDataTask, OptimizeDatabaseTask. Only timer-driven runs are gated;
manual and API-triggered runs always execute locally.
PostgreSQL provider
src/Jellyfin.Database/Jellyfin.Database.Providers.PostgreSQL/ is an EF Core
provider parallel to the SQLite one, selected with
DatabaseType: Jellyfin-PostgreSQL. It carries a single initial migration
generated against the v12.0 model. SQLite remains the default, so existing
deployments are unaffected.
tools/Jellyfin.DbMigrator/ moves an existing jellyfin.db into PostgreSQL,
optionally uploading a pre-migration copy of the SQLite file to S3.
Modified upstream files
| File | Change |
|---|---|
Jellyfin.Server/CoreAppHost.cs (+46) |
Registers the Redis or null transcode store and scan-leader lease from startup config |
Jellyfin.Api/Controllers/DynamicHlsController.cs (+133/-9) |
Registers the play session, runs lease renewal, and shortens segments when resuming a stored session |
Emby.Server.Implementations/ScheduledTasks/Tasks/DeleteTranscodeFileTask.cs (+52/-6) |
Keeps files belonging to an active session in the store |
Emby.Server.Implementations/Session/SessionManager.cs (+37/-4) |
Persists and deletes the durable live stream record |
Emby.Server.Implementations/ScheduledTasks/ScheduledTaskWorker.cs (+28/-1) |
Skips timer-driven gated tasks without the leader lease |
Emby.Server.Implementations/ScheduledTasks/TaskManager.cs (+12/-2) |
Passes the lease and options to each worker |
Jellyfin.Server.Implementations/Extensions/ServiceCollectionExtensions.cs (+53) |
Registers the PostgreSQL provider and a pooled NpgsqlDataSource |
Jellyfin.Server/Program.cs (+5) |
Exposes IServerConfigurationManager to the startup migration container |
MediaBrowser.Model/Configuration/EncodingOptions.cs (+16) |
Adds RecoverySegmentLengthSeconds and RecoverySegmentBufferCount |
Directory.Packages.props, Jellyfin.sln, four .csproj files |
New packages, projects and references |
tests/.../SessionManagerTests.cs, tests/.../IdlePlaybackTests.cs |
Pass the new constructor argument |
Deleted upstream files
.github/workflows/* (15 files). The fork is hosted on Gitea and builds on
Woodpecker via .woodpecker/ci.yaml.
Rebasing onto a newer upstream release
git remote add upstream https://github.com/jellyfin/jellyfin.git
git fetch upstream --tags
# files this fork owns outright
git diff v12.0...HEAD --name-only --diff-filter=A
# files that need re-porting onto the new release
git diff v12.0...HEAD --name-only --diff-filter=M
# upstream churn on a touched file since this base
git log v12.0..<new-tag> --oneline -- <path>
Re-apply the modified-file changes onto the new upstream code rather than reverting upstream's changes to make a patch apply.