Self-Hosting Jellyfin Media Server on a KVM VPS: 4K Transcoding, 1 Gbps Bandwidth, and Docker Setup

10/4/202638 min read

Tropic

jellyfin media server on vps
jellyfin vps docker
self hosted plex alternative vps
jellyfin 4k transcoding vps
install jellyfin ubuntu server

Quick Takeaway: Production-grade Jellyfin deployments streaming concurrent 4K HEVC Remux media require a dedicated KVM VPS provisioned with at least 4 dedicated vCPUs (≥3.5 GHz for CPU decode fallback or VA-API/QSV passthrough via /dev/dri), 8 GB RAM, and enterprise PCIe 4.0 NVMe storage to eliminate SQLite concurrency bottlenecks and I/O wait during transcode chunking. Preventing playback buffering across high-bitrate WAN clients demands an unmetered 1 Gbps full-duplex uplink tuned with the Linux kernel TCP BBR congestion control algorithm (net.ipv4.tcp_congestion_control = bbr) and reverse-proxied over HTTP/3 (QUIC) to keep p99 stream initialization latency under 100 ms. Deploying the workload via Docker Compose with strict cgroups v2 resource boundaries (memory.max = 6G, cpu.weight) and a tmpfs transcode scratchpad ensures predictable performance without inducing NVMe write exhaustion or triggering the host OOM killer.

Hardware Sizing and Bandwidth Requirements for 4K Media Streaming
Network Optimization: TCP BBR and Socket Tuning for Smooth 60 FPS Video
Deploying Jellyfin with Docker Compose and Persistent Storage Mounts
Configuring Caddy Reverse Proxy with Automatic HTTPS and WebSockets
Transcoding Profiles: HEVC/H.264, Bitrate Throttling, and Client Apps
Backup Automation and Complete Disaster Recovery Procedure
Frequently Asked Questions (FAQ)

Hardware Sizing and Bandwidth Requirements for 4K Media Streaming

Deploying a self-hosted Jellyfin media server on VPS infrastructure for high-bitrate 4K streaming demands a precise separation between compute-bound video encoding, memory-backed scratch caching, and packet-pacing network throughput. Underestimating any tier causes immediate client playback degradation: pipeline stalls in HLS chunk generation manifest as spinning loaders, while packet retransmissions over saturated uplinks trigger frame drops and audio-video desync.

Architecting this workload begins with understanding the distinct mechanical demands of Direct Play versus Software Transcoding on hypervisor-managed virtual hardware.

+-----------------------------------------------------------------------------------+
|                           JELLYFIN PIPELINE TOPOLOGY                              |
+-----------------------------------------------------------------------------------+

 [ NVMe Storage: 4K Media Container ]                                               
        │                                                                           
        │ Sequential Block Read (Direct I/O)                                        
        ▼                                                                           
 [ FFmpeg / Jellyfin Demuxer ]                                                      
        │                                                                           
        ├─────────────────────────────────────────────────┐                         
        │ Client Supports HEVC Main10 + Target Bitrate    │ Client Incompatible /   
        │                                                 │ Bandwidth Constrained   
        ▼ (Direct Play)                                   ▼ (Transcoding Required)  
 [ Zero-Copy Network Delivery ]                    [ Software Transcode Core ]      
        │                                                 │                         
        │ Sendfile / TCP Pacing                           ├─ libx264 / libsvtav1    
        │                                                 ├─ Tone Mapping (zscale)  
        │                                                 ▼                         
        │                                          [ In-Memory tmpfs Buffer ]       
        │                                                 │ (/dev/shm Segmenting)   
        │                                                 ▼                         
        └────────────────────────────────────────> [ HLS / VOD Web Server ]         
                                                          │                         
                                                          ▼ TCP BBR (Paced Flow)    
                                                   [ WAN Remote Client ]

Compute Allocation: Direct Play vs. Software Transcoding

Direct Play places near-zero computational overhead on the host. The server process merely acts as an authenticated asynchronous file streamer, demuxing the Matroska (.mkv) or MP4 container and forwarding the underlying H.265/HEVC video and Dolby Digital/TrueHD audio bitstreams directly over HTTP/1.1 or HTTP/2. A baseline configuration of 2 dedicated vCPUs can easily saturate a 1 Gbps link with Direct Play streams, maintaining CPU utilization below 5%.

Software transcoding (CPU-based video rendering via ffmpeg using libx264 or libsvtav1) represents the opposite extreme. Because standard KVM VPS instances do not expose dedicated graphics compute hardware (Intel QuickSync Video via /dev/dri/renderD128 or NVIDIA NVENC via proprietary VFIO drivers), the hypervisor's physical CPU cores must execute all frame decoding, pixel-format transformation, tone-mapping, and re-encoding through pure software rasterization.

The 4K HDR Tone-Mapping Penalty

When transcode sessions convert a 4K HDR10/Dolby Vision HEVC source down to a 1080p SDR H.264 stream for an incompatible web browser or legacy display, computational complexity surges exponentially: 1. Decode: HEVC 10-bit (Main10 profile) at $3840 \times 2160$, 60 fps. 2. Color Space Conversion: Tone mapping BT.2020 color gamut with SMPTE ST 2084 (PQ) or HLG transfer characteristics to standard Rec.709 via the zscale or tonemap software filters. 3. Scale: Bicubic or Lanczos downsampling to $1920 \times 1080$. 4. Encode: 8-bit YUV420p compression using libx264 at preset veryfast or faster.

A single real-time 4K HDR software transcode stream requires an allocation equivalent to 14,000–17,000 PassMark points, translating to 6 to 8 dedicated high-frequency CPU cores (3.5+ GHz base clock) running AVX2/AVX-512 vector extensions at sustained 100% utilization. If the virtualized environment suffers from oversubscribed physical cores, thread execution stalls, causing the transcode speed parameter to drop below 1.0x (yielding frame buffering on the client).

+-----------------------------------------------------------------------------------------+
|                  HYPERVISOR CPU SCHEDULING INTEGRITY UNDER AVX2 LOAD                   |
+-----------------------------------------------------------------------------------------+

 OVERSUBSCRIBED HYPERVISOR (Noisy Neighbor Contention)
 [Core 0] [Task A] ──> [ CPU Steal Time (%st > 5.0%) ] ──> [ Audio/Video Desync ]
 [Core 1] [Task B] ──> [ Frame Queue Drops Below 24fps] ──> [ Playback Stutter  ]

 DEDICATED KVM CORE ALLOCATION (tropic.host Standard)
 [vCPU 0] ────────────> [ Sustained 4.5 GHz AVX-512 ] ────> [ Transcode Speed: 1.45x ]
 [vCPU 1] ────────────> [ Zero Waitstates (%st = 0.0%)] ──> [ Stable HLS Delivery   ]

To guarantee deterministic transcoding throughput, hosting your Jellyfin media server on VPS instances deployed on tropic.host ensures bare-metal parity: virtualization runs on bare-metal KVM with strict $1:1$ vCPU-to-thread affinity on AMD EPYC 9004 and AMD Ryzen 9 processors. This ensures 0.0% CPU Steal Time (%st = 0.0%), preventing background hypervisor scheduling latency from interrupting active FFmpeg worker threads.

Memory Sizing: Buffer Pools, Linux Page Cache, and RAM Transcoding

A common architectural failure in media server sizing is routing FFmpeg's transient transcode output to disk storage. Transcoding generates millions of small 6-second MPEG-TS (.ts) or fragmented MP4 (.m4s) segment files. Writing and unlinking these files on block storage incurs heavy filesystem journal thrashing, inflates inode consumption, and creates write-amplification penalties that degrade drive endurance.

Transcode-to-RAM via `tmpfs`

The transcode directory must reside in an in-memory tmpfs filesystem. Calculate required tmpfs capacity using the peak concurrent transcode metric:

$$\text{RAM}{\text{tmpfs}} = N{\text{streams}} \times (\text{Bitrate}{\text{target}} \times T{\text{buffer}}) \times 1.5$$

For a production environment hosting 3 concurrent 1080p transcodes (target bitrate 15 Mbps, maintaining a 300-second throttle window ahead of playback): * Per-stream buffer: $\frac{15 \text{ Mbps} \times 300 \text{ s}}{8 \times 1024} \approx 550 \text{ MB}$. * Total active transcode scratch space: $3 \times 550 \text{ MB} \times 1.5 \approx 2.5 \text{ GB}$.

Page Cache Allocation

Independent of transcoding scratchpad memory, the Linux kernel relies on unused physical RAM as an aggressively managed page cache (Cached in /proc/meminfo). When streaming high-bitrate 4K remuxes (50–90 GB container sizes), large readahead operations keep incoming media blocks resident in volatile memory. Sizing the VPS with insufficient memory forces kernel page reclamation (kswapd0 activity), driving I/O waits up and causing network throughput spikes.

Production memory sizing benchmarks: * Direct Play Only (1–5 concurrent users): 4 GB RAM minimum. * Mixed Workload (1x 4K Transcode or 3x 1080p Transcodes): 8 GB to 16 GB RAM with 4 GB reserved for /dev/shm. * High-Density Production (Multi-tenant): 32 GB RAM with 12 GB reserved for /dev/shm.

Storage I/O Profile: QD1 Random Reads and Sequential Streaming

Media streaming workloads exhibit a dual I/O profile. Reading source media files demands sustained, high-bandwidth sequential read performance. Concurrently, database operations (Jellyfin's internal SQLite database or an external PostgreSQL instance recording playback progression, artwork caching, and file analysis) generate low-queue-depth random I/O:

Media Ingestion and Retrieval: 15–20 MB/s sustained sequential read per active 4K remux client.
Metadata and Image Generation: High-frequency, random $4\text{ KB}$ read/write operations hitting the /config and /cache volumes.

Consumer-grade VPS platforms utilizing networked block storage (e.g., Ceph over congested backplanes) introduce unpredictable p99 I/O latency spikes exceeding 100 ms. These latency spikes stall FFmpeg demuxing threads.

Running your workload on tropic.host provides direct access to enterprise-grade PCIe 4.0 NVMe SSD arrays capable of delivering $> 50,000\text{ IOPS}$ at random $4\text{ KB}$ QD1 reads, keeping system I/O wait (%iowait) at a flat 0.0% even during concurrent library scans and multi-client sequential streaming.

Network Sizing and Burst Profile: Overcoming BDP and Congestion

Network sizing for 4K streaming cannot be calculated using static average bitrates. A 4K HDR Blu-ray remux encoded at an average bitrate of 65 Mbps frequently spikes to 120–160 Mbps during complex, high-entropy scenes (e.g., sequences with fine film grain, rapid motion, or pyrotechnics).

+-----------------------------------------------------------------------------------+
|               4K REMUX BITRATE FLUCTUATION vs. BURST PROVISIONING                 |
+-----------------------------------------------------------------------------------+
 200 Mbps ──┐                                                                        
            │                                    /---\       [p99 Burst: 165 Mbps]  
 150 Mbps ──┼───                  /---\         /     \                             
            │  / \               /     \       /       \--/                         
 100 Mbps ──┼-/---\-------------/-------\-----/----------------                     
            │/     \   /---\   /         \   /             \                        
  50 Mbps ──┼───────\-/-----\-/-----------\-/--------------- [Average: 65 Mbps]     
            │                                                                       
   0 Mbps ──┴───────────────────────────────────────────────────────> Timeline (sec)

Furthermore, video streaming clients deploy aggressive initial buffering strategies. Upon playback initiation, the client player requests chunks as rapidly as possible to fill its local 30- to 60-second forward buffer, temporarily consuming 250–400 Mbps of burst bandwidth for 5 to 10 seconds. If the VPS uplink is capped at a standard 100 Mbps or 250 Mbps tier, client startup times degrade from sub-second playback to 8–12 seconds of connection negotiation latency.

Network Buffer Optimization: Kernel Tuning for TCP BBR

Standard Linux TCP stacks deploy the cubic congestion control algorithm, which misinterprets minor packet drops on high Bandwidth-Delay Product (BDP) cross-border routes as network congestion, cutting the TCP congestion window (cwnd) by half.

To maintain continuous 4K streaming across international peering links, the Linux kernel must be configured to use TCP BBR (Bottleneck Bandwidth and RTT) combined with Fair Queuing (fq). BBR models the physical network pipe dynamically, pacing packets to prevent bufferbloat while sustaining peak wire speeds even under 1–2% random packet loss environments.

Apply the following production parameters to /etc/sysctl.d/99-jellyfin-network.conf:

# Enforce Fair Queuing packet scheduler and TCP BBR congestion control
net.core.default_qdisc = fq
net.ipv4.tcp_congestion_control = bbr

# Increase maximum socket receive and send buffer sizes for high-BDP WAN paths
net.core.rmem_max = 67108864
net.core.wmem_max = 67108864
net.core.rmem_default = 33554432
net.core.wmem_default = 33554432

# Autotuning memory limits: min, default, max buffer sizes (in bytes)
net.ipv4.tcp_rmem = 4096 87380 33554432
net.ipv4.tcp_wmem = 4096 65536 33554432

# Expand network core backlog and backlog queues for incoming bursts
net.core.netdev_max_backlog = 10000
net.core.somaxconn = 8192

# Enable TCP window scaling (RFC 1323)
net.ipv4.tcp_window_scaling = 1

# Disable TCP slow start after idle to maintain high streaming window sizing
net.ipv4.tcp_slow_start_after_idle = 0

Load the sysctl configuration into runtime memory:

sysctl --system

With tropic.host's standard 1–10 Gbps unmetered premium uplinks with native TCP BBR routing and direct BGP interconnects at Tier-1 internet exchanges in Frankfurt, Amsterdam, London, and Singapore, round-trip packet pacing remains stable, achieving a p99 frame delivery latency of under 45 ms internationally.

Hardware Sizing Matrix for Jellyfin on VPS

The following matrix outlines the validated hardware specifications required across production streaming profiles:

Workload Profile	Video Codec & Stream Characteristics	Target Stream Mode	Dedicated vCPUs (`%st = 0.0%`)	System RAM & `tmpfs` Allocation	Minimum Storage Subsystem	Recommended Network Uplink	Validated tropic.host Tier
Personal Streamer	1x 4K HDR10 (HEVC @ 60 Mbps)	Direct Play	2 vCPUs (AMD EPYC/Ryzen)	4 GB RAM / No `tmpfs` required	Enterprise NVMe (PCIe 4.0)	1 Gbps Port (Bursts to 250 Mbps)	Starter KVM NVMe
Direct Home Lab	4x 4K UHD Remux (HEVC @ 80 Mbps)	Direct Play	4 vCPUs (AMD EPYC/Ryzen)	8 GB RAM / No `tmpfs` required	Enterprise NVMe ($> 30\text{k}$ IOPS)	1 Gbps Port (Bursts to 600 Mbps)	Pro KVM NVMe
Single 4K Transcode	1x 4K HDR10 $\to$ 1080p SDR (Tone mapped)	Software Transcode (`libx264`)	8 vCPUs (Sustained $\ge 3.5\text{ GHz}$)	16 GB RAM (4 GB allocated to `tmpfs`)	Enterprise NVMe ($> 50\text{k}$ IOPS)	1 Gbps Port (Unthrottled)	Compute Ultra KVM
Family Mixed Tier	2x 4K Direct Play + 2x 1080p Transcodes	Mixed Mode	12 vCPUs (Dedicated AVX2/512)	24 GB RAM (8 GB allocated to `tmpfs`)	Dual Enterprise NVMe in RAID-1	2.5 Gbps Port	Enterprise Cloud KVM
Multi-Tenant Hub	5x 4K Direct Play + 3x 1080p Transcodes	Mixed Mode	16–24 vCPUs (EPYC 9004 / 9950X)	32–64 GB RAM (16 GB `tmpfs` transcode)	Direct PCIe 4.0 NVMe Array	10 Gbps Premium Uplink	High-Frequency Dedicated KVM

Production Deployment: Resource Limits and In-Memory Buffer Orchestration

To operationalize these resource constraints and prevent memory leakage or runaway CPU allocation from freezing the host operating system, define strict kernel boundaries using Linux cgroups v2 directives inside your container engine.

The following production docker-compose.yml configures hard systemd/cgroups limits and mounts an isolated in-memory scratch space directly mapped to the host's virtual memory subsystem (/dev/shm):

services:
  jellyfin:
    image: jellyfin/jellyfin:10.9.11
    container_name: jellyfin_production
    restart: unless-stopped
    user: "1000:1000"
    network_mode: "host"
    environment:
      - JELLYFIN_PublishedServerUrl=https://media.example.com
      - MALLOC_TRIM_THRESHOLD_=131072
    volumes:
      # Persistent configuration and metadata database files
      - /opt/jellyfin/config:/config:rw
      - /opt/jellyfin/cache:/cache:rw
      # High-performance media volume mounted direct from NVMe storage
      - /mnt/storage/media:/media:ro
      # In-memory RAM disk allocation for HLS transcode chunk generation
      - type: tmpfs
        target: /transcode
        tmpfs:
          size: 4294967296  # 4 GB allocated RAM
          mode: 1777        # Sticky bit permissions for non-root execution
    deploy:
      resources:
        limits:
          cpus: '8.000'     # Pin compute ceiling to 8 dedicated cores
          memory: 12G       # Absolute upper ceiling enforcing OOM boundaries
        reservations:
          cpus: '4.000'     # Guaranteed CPU baseline allocation
          memory: 6G        # Guaranteed memory reserve
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Verifying CPU Steal and System Scheduler Overhead

Once the container is initialized under continuous load, audit the host metrics to confirm the hypervisor is not starving transcoding processes:

# Verify hypervisor CPU steal time remains strictly at 0.0% under load
mpstat 1 5

Linux 6.8.0-45-generic (jellyfin-host)    10/04/2026   _x86_64_   (8 CPU)

02:14:01 PM  CPU    %usr   %nice    %sys %iowait    %irq   %soft  %steal  %guest  %idle
02:14:02 PM  all   86.42    0.00    5.12    0.00    0.00    0.86    0.00    0.00   7.60
02:14:03 PM  all   87.10    0.00    4.98    0.00    0.00    0.74    0.00    0.00   7.18
02:14:04 PM  all   86.85    0.00    5.20    0.00    0.00    0.81    0.00    0.00   7.14

A consistent value of 0.00 in the %steal column confirms dedicated hardware resource isolation. If this value climbs above 1.50, hypervisor core overcommitment is actively degrading the media pipeline, requiring immediate migration to guaranteed KVM virtualization.

Network Optimization: TCP BBR and Socket Tuning for Smooth 60 FPS Video

High-bitrate 1080p60 and 4K60 streaming pipelines impose continuous, non-linear pressure on the Linux network stack. Unlike static file downloads that saturate bandwidth linearly, media servers like Jellyfin rely on chunked delivery—predominantly HTTP Live Streaming (HLS) or fragmented MP4 (fMP4) over HTTP/1.1 or HTTP/2. A video client downloads a 2-to-6-second media segment at maximum line rate, buffers the data, drops into an idle period during playback, and then requests the next segment.

On unoptimized Linux installations, default kernel socket buffers and legacy congestion control algorithms interpret these burst-and-idle cycles as network instability, triggering throughput collapses, packet drops, and severe playback buffering.

The Problem with Loss-Based Congestion Control (CUBIC)

Most Linux distributions default to the CUBIC congestion control algorithm. CUBIC is loss-based: it assumes that any dropped packet indicates physical network congestion. In response, CUBIC slashes the congestion window (cwnd) by 30% to 50%, slowly ramping it back up.

Over public WAN routes, residential Wi-Fi, and 5G cellular uplinks, random packet loss occurs continuously due to radio interference, cross-traffic jitter, and ISP middlebox throttling, entirely unrelated to link capacity. When a Jellyfin stream encounters a minor 1% packet loss event under CUBIC, the server throttles its transmission rate, the client-side buffer runs dry, and the video player stalls.

TCP CUBIC (Loss-Based):
Packet Loss Detected ───────► Slashes cwnd by 30-50% ───────► Buffer Underrun (Stall)
                                                              ▲
TCP BBR (Model-Based):                                        │
Packet Loss Detected ───────► Measures Max BW & Min RTT ────► Maintains Full Pacing Rate

Google’s Bottleneck Bandwidth and Round-trip propagation time (BBR) congestion control eliminates this failure mode. BBR builds an active mathematical model of the network path using two real-time metrics: 1. Bottleneck Bandwidth: The maximum physical delivery rate observed across the link. 2. Round-Trip Propagation Time (RTprop): The true physical latency of the connection, excluding buffer queuing.

By decoupling congestion control from packet loss, BBR sustains maximum throughput even over paths with up to 15–20% random packet loss, delivering consistent 60 FPS video streams without player stalls.

Tuning the Linux TCP Stack for Media Streaming

Achieving seamless, artifact-free playback requires configuring BBR alongside Fair Queueing (fq) and resizing socket memory boundaries to accommodate large Bandwidth-Delay Products (BDP).

The Bandwidth-Delay Product defines the volume of unacknowledged data that must remain in flight to fully saturate a network connection:

$$\text{BDP (bytes)} = \frac{\text{Link Bandwidth (bits/sec)}}{8} \times \text{RTT (seconds)}$$

For a remote client streaming a 40 Mbps 4K60 stream across a transit path with an 80 ms RTT, the baseline BDP is:

$$\text{BDP} = \left(\frac{40{,}000{,}000}{8}\right) \times 0.080 = 400{,}000 \text{ bytes (400 KB)}$$

When serving concurrent streams over multi-hundred-megabit connections, Linux's legacy default buffer ceiling of 212 KB forces the TCP send window to close prematurely, capping throughput far below available hardware limits.

Create a dedicated sysctl configuration file at /etc/sysctl.d/99-jellyfin-network.conf:

# /etc/sysctl.d/99-jellyfin-network.conf
# Target: High-throughput, low-latency media delivery for Jellyfin

# 1. Congestion Control and Packet Pacing
# BBR strictly requires the 'fq' (Fair Queueing) qdisc to enforce pacing
net.core.default_qdisc = fq
net.ipv4.tcp_congestion_control = bbr

# 2. Prevent TCP Slow Start Reset After Idle
# Critical for HLS/DASH: Prevents the kernel from resetting cwnd to the initial window
# during client playback pauses between segment downloads
net.ipv4.tcp_slow_start_after_idle = 0

# 3. Socket Memory Boundaries (Min, Default, Max in bytes)
# Max buffer set to 16 MB to allow high BDP over long-haul transit
net.ipv4.tcp_rmem = 4096 87380 16777216
net.ipv4.tcp_wmem = 4096 65536 16777216
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216

# 4. Network Device Queues and Connection Backlogs
# Prevents SYN packet drop under burst traffic
net.core.netdev_max_backlog = 16384
net.core.somaxconn = 8192
net.ipv4.tcp_max_syn_backlog = 8192

# 5. Bufferbloat Mitigation and Scrubbing Responsiveness
# Caps unsent socket buffer data to 16 KB, minimizing head-of-line blocking
# and ensuring immediate response when the client seeks or scrubs the timeline
net.ipv4.tcp_notsent_lowat = 16384

# 6. Path MTU Discovery and Anti-Blackhole Protection
net.ipv4.tcp_mtu_probing = 1

# 7. Fast Socket Reclamation
net.ipv4.tcp_fin_timeout = 15
net.ipv4.tcp_tw_reuse = 1

Parameter Breakdown

net.core.default_qdisc = fq: BBR depends on the Fair Queueing packet scheduler. fq paces packets out to the network interface card (NIC) evenly over the estimated round-trip time, eliminating micro-bursts that trigger queue drops at upstream ISP switches.
net.ipv4.tcp_slow_start_after_idle = 0: By default, the Linux kernel sets this to 1, meaning that if a connection is silent for one round-trip timeout (RTO), it collapses the congestion window back to tcp_init_cwnd (typically 10 packets). In video streaming, where the client pauses between segment downloads, this default continuously forces the connection through slow start, severely throttling transfer rates. Disabling it preserves the discovered line rate.
net.ipv4.tcp_notsent_lowat = 16384: When a client scrubs the video timeline or switches audio tracks, the video player aborts the current TCP connection or issues an HTTP range cancellation. If hundreds of kilobytes of unread video frames sit queued inside the kernel write buffer, client latency spikes. Limiting the unsent write queue to 16 KB forces the application layer to deliver data incrementally, reducing p99 seek latency from upwards of 1,200 ms to under 40 ms.

Apply the parameters immediately without rebooting:

sudo sysctl --system

Verifying BBR and Pacing in Production

Confirm that BBR is actively handling outbound media traffic on your network interfaces.

Check the global kernel algorithm state:

sysctl net.ipv4.tcp_congestion_control net.core.default_qdisc

net.ipv4.tcp_congestion_control = bbr
net.core.default_qdisc = fq

Verify that the Fair Queueing discipline is running on the primary network interface (e.g., eth0):

tc qdisc show dev eth0

qdisc fq 8001: root refcnt 2 limit 10000p flow_limit 100p buckets 1024 orphan_mask 1023 quantum 3028 initial_quantum 15140

To verify live socket performance during an active Jellyfin 4K stream, query the socket statistics using ss. Filter for Jellyfin’s default HTTP port (8096) or reverse proxy TLS port (443):

ss -tino '( sport = :8096 or sport = :443 )'

ESTAB 0 16384 198.51.100.10:443 203.0.113.45:52412
     bbr wscale:7,7 rto:44 rtt:21.842/0.412 ato:40 mss:1460 rcvspace:14600
     rcv_rtt:21.842 rcv_space:14600 ssthresh:14 cwnd:42
     pacing_rate 128.4Mbps delivery_rate 94.2Mbps
     minrtt:20.104 notsent:0

Key output indicators: * bbr: Confirms the kernel has assigned BBR to the client socket. * pacing_rate 128.4Mbps: Confirms fq is smoothing packet egress to match link delivery rate. * notsent:0: Confirms tcp_notsent_lowat is preventing bufferbloat inside the local socket buffer.

Container Network Namespaces: Host Mode vs. Bridge Mode

When deploying Jellyfin inside Docker, network isolation can inadvertently isolate your container from host-level sysctl tunings.

If the container runs in standard Docker bridge mode (network_mode: bridge), certain network namespaces isolate loopback and local TCP parameters. For maximum network throughput and minimal translation overhead, use network_mode: host in your docker-compose.yml:

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    network_mode: host
    restart: unless-stopped
    # Environment and volume mounts omitted for brevity

Running in host mode eliminates Docker’s docker-proxy userland process and kernel network address translation (NAT) overhead via iptables/nftables. This directly exposes host NIC interfaces, cutting packet processing latency, preserving clean client IP attribution for fail2ban logging, and ensuring that all tuned sysctl buffer allocations apply directly to outbound media streams.

Upstream Network Quality and Peering Considerations

Kernel and socket optimizations cannot compensate for degraded transit routing or packet drops originating inside an overcommitted hosting hypervisor. If the host infrastructure suffers from CPU steal time (%st > 0.0%), the hypervisor will delay network interrupt processing (softirq), resulting in jitter and dropped packets at the virtual network adapter (virtio-net).

For production media servers, the underlying virtual machine must be backed by guaranteed hardware resources. Deploying on tropic.host provides a reliable foundation: clean KVM virtualization ensures dedicated CPU allocations with zero oversubscription (%st = 0.0%), allowing the virtual network interface to process high-throughput interrupt routines without frame loss.

Furthermore, tropic.host nodes provide 1–10 Gbps uplinks with direct BGP peering at central Internet exchanges (including DE-CIX Frankfurt, AMS-IX Amsterdam, and LINX London). Connecting to direct, low-hop transit paths ensures that tuned BBR socket buffers operate against stable round-trip times, sustaining unbuffered 60 FPS video delivery to remote clients.

Deploying Jellyfin with Docker Compose and Persistent Storage Mounts

Operating a production-grade containerized media stack requires isolating application state, mitigating disk write amplification, and enforcing strict kernel-level resource boundaries. When deploying a Jellyfin media server on VPS instances, relying on ad-hoc docker run commands introduces configuration drift and complicates lifecycle management. A declarative Docker Compose manifest backed by optimized directory structures and explicit POSIX access controls guarantees repeatable deployments and predictable runtime behavior.

Directory Topology and Storage Architecture

Jellyfin generates three distinct classes of persistent data, each exhibiting radically different I/O patterns:

Configuration and Database State (/config): Houses system configurations, user metadata, and SQLite database clusters (jellyfin.db and library.db). This path is dominated by high-frequency, low-latency random 4K read/write queries.
Metadata Cache (/cache): Stores dynamically generated image transcode caches, extracted chapter thumbnail trickplay files (.bif), and web client bundles.
Transient Transcoding Workspace (/transcode): Receives real-time fragmented HLS (.ts) video chunks, subtitle rasterizations, and remuxed transport streams. This workload is purely write-heavy and ephemeral.

Placing all three paths onto a generic, unoptimized root filesystem leads to severe I/O contention. In virtualized environments, SQLite write-ahead logging (WAL) commits to /config will stall if concurrent video transcoding saturates the storage queue depth, causing API timeouts and playback stutter.

To eliminate filesystem overhead, execute the following host preparation script to establish dedicated directory hierarchies and a non-privileged runtime identity:

# Create an unprivileged system user and group for the media service
sudo groupadd -g 1001 media
sudo useradd -u 1001 -g media -s /usr/sbin/nologin -M -d /opt/jellyfin media

# Establish deterministic directory hierarchy
sudo mkdir -p /opt/jellyfin/{config,cache,media}
sudo chown -R 1001:1001 /opt/jellyfin
sudo chmod -R 750 /opt/jellyfin

# Tune filesystem mount attributes for SQLite performance
# Ensure the underlying mountpoint utilizes noatime to eliminate metadata update overhead on reads
sudo tune2fs -o journal_data_writeback /dev/disk/by-label/vps-root 2>/dev/null || true

Mounting the VPS storage volume with the noatime,nodiratime flags eliminates write amplification caused by the Linux VFS updating access timestamps every time Jellyfin queries poster assets or SQLite page files. On high-performance KVM instances from tropic.host, the underlying infrastructure utilizes enterprise-grade PCIe 4.0 NVMe SSDs delivering over 50,000 random 4K QD1 read IOPS. This architecture ensures that SQLite fsync() operations achieve p99 latencies well below 200 microseconds, preventing lock contention even during multi-user parallel library updates.

Ephemeral Transcoding: RAM Disk (tmpfs) vs. NVMe Disk

Transcoding a single 4K HEVC 10-bit stream at 60 Mbps to 1080p H.264 generates hundreds of megabytes of intermediate .ts segments every minute. Writing these short-lived chunks to flash storage consumes limited solid-state disk endurance (Terabytes Written — TBW) and introduces filesystem lock contention.

To avoid flash degradation, the /transcode directory must be mapped as an in-memory tmpfs mount whenever host RAM permits. A 4 GB RAM disk comfortably buffers multiple concurrent 1080p transcode sessions without exhausting system memory.

Parameter	`tmpfs` (RAM Disk)	Direct NVMe Storage
Write Latency (p99)	$< 1\,\mu\text{s}$ (DRAM bus access)	$150 - 300\,\mu\text{s}$ (PCIe NVMe controller)
Storage Wear (TBW)	Zero flash wear	Up to 150–400 GB/day per heavy stream
RAM Footprint	Dynamic (bounded by `size=4g`)	Negligible host RAM overhead
Failure Mode	Transcode fails with `ENOSPC` if full	Host storage fills if cleanup process stalls
Recommended Use	Production VPS with $\ge 8\text{ GB}$ RAM	Budget VPS with $\le 4\text{ GB}$ RAM

Hardened Production `docker-compose.yml`

The following configuration implements host networking, mounts /transcode directly into virtual memory, drops unnecessary Linux capabilities, and applies deterministic cgroups v2 resource limits:

version: "3.8"

services:
  jellyfin:
    image: jellyfin/jellyfin:10.9.11
    container_name: jellyfin
    restart: unless-stopped

    # Bypass userland proxy and NAT; bind directly to virtio-net adapter
    network_mode: "host"

    user: "1001:1001"

    environment:
      - JELLYFIN_PublishedServerUrl=https://media.example.com
      - DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=0
      - LC_ALL=en_US.UTF-8
      - LANG=en_US.UTF-8
      - TZ=Etc/UTC

    volumes:
      # Persistent configuration and SQLite databases
      - type: bind
        source: /opt/jellyfin/config
        target: /config
        read_only: false

      # Ephemeral web and image metadata cache
      - type: bind
        source: /opt/jellyfin/cache
        target: /cache
        read_only: false

      # Read-only media storage mount to prevent container-level corruption
      - type: bind
        source: /opt/jellyfin/media
        target: /media
        read_only: true

    # Ephemeral RAM disk to offload transcode I/O from storage drives
    tmpfs:
      - /transcode:rw,noexec,nosuid,size=4294967296

    # Security profile and capability pruning
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETUID
      - SETGID

    # Production resource constraints managed via cgroups v2
    deploy:
      resources:
        limits:
          cpus: "4.0"
          memory: 6144M
        reservations:
          cpus: "1.0"
          memory: 2048M

    # Process health check to detect deadlocked threads
    healthcheck:
      test: ["CMD-SHELL", "curl -f -s http://127.0.0.1:8096/health || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s

    # Logging constraints to prevent log partition exhaustion
    logging:
      driver: "json-file"
      options:
        max-size: "20m"
        max-file: "3"

Key Architectural Directives

network_mode: "host": Eliminates overhead from iptables connection tracking (conntrack) and the Docker userland proxy. Network sockets bind straight to the host interface, preserving external client IPv4 addresses for ingress rate-limiting and connection auditing.
tmpfs: /transcode: Restricts temporary video chunks to memory using size=4294967296 (4 GB). Mount options noexec and nosuid prevent execution of binary exploits inside the scratch space.
security_opt: [no-new-privileges:true]: Blocks privilege escalation attacks through SUID binaries inside the container filesystem.
read_only: true on /media: Enforces strict read-only access to host media assets. Even if a zero-day vulnerability in Jellyfin’s web parser allows remote code execution within container boundaries, library files cannot be encrypted, modified, or deleted.
cgroups v2 Enforcement: Limits the container to 4 CPU cores and 6 GB RAM (memory.max). The reservation ensures that the kernel OOM-killer prioritizes background daemon tasks elsewhere on the host before terminating Jellyfin's critical streaming thread.

Deployment and Runtime Verification

Deploy the stack and verify the container cgroups limits and health status directly against the host runtime:

# Pull image layers and initialize service in detached mode
cd /opt/jellyfin
docker compose up -d

# Verify runtime initialization and port binding
docker compose ps
ss -tlpn | grep 8096

# Audit cgroups v2 memory limits applied by systemd
systemd-cgls /docker/$(docker inspect --format '{{.Id}}' jellyfin) 2>/dev/null || \
cat /sys/fs/cgroup/system.slice/docker-$(docker inspect --format '{{.Id}}' jellyfin).scope/memory.max

# Confirm SQLite WAL mode activation inside the configuration volume
docker compose exec jellyfin sqlite3 /config/data/jellyfin.db "PRAGMA journal_mode;"

The output for PRAGMA journal_mode; must return wal. Write-Ahead Logging allows simultaneous non-blocking reads while active writes append sequentially to the .db-wal file. Running on NVMe-backed KVM virtual machines provided by tropic.host ensures zero CPU steal time (%st = 0.0%), meaning container execution threads are never preempted by the hypervisor during transactional disk synchronization.

Configuring Caddy Reverse Proxy with Automatic HTTPS and WebSockets

Exposing a jellyfin media server on vps directly to the public internet on unencrypted HTTP port 8096 introduces severe transport vulnerabilities, breaks modern browser media capabilities (such as WebAssembly decoders, Cast API integrations, and secure cookie contexts), and denies clients the concurrency benefits of HTTP/2 and HTTP/3 (QUIC). While traditional web servers like Nginx or HAProxy require external certbot crons, manual Diffie-Hellman parameter generation, and explicit WebSocket upgrade blocks, Caddy v2 natively provides automated TLS lifecycle management, out-of-the-box HTTP/3 negotiation over UDP, and zero-configuration transparent WebSocket forwarding.

In a streaming pipeline, the edge proxy sits directly in the hot path of video transport. Unoptimized proxy buffering or undersized socket buffers inevitably lead to elevated p99 Time to First Frame (TTFF) metrics and video playback stalls during high-bitrate direct-play or transcoded segment transfers.

Host Kernel Tuning for High-Throughput HTTP/3 (QUIC)

Because HTTP/3 operates over UDP rather than TCP, connection state and congestion recovery are handled entirely in userspace by Caddy’s Go runtime. If the underlying Linux kernel UDP receive buffers are left at default values (typically 208 KB), sudden bursty I/O from 4K HEVC remuxes (bitrates exceeding 80–120 Mbps) will overflow socket queues, triggering silent UDP packet drops, aggressive retransmissions, and player micro-buffering.

Apply high-bandwidth, low-latency socket buffer profiles across the network stack before binding Caddy to public ports:

# Append kernel socket buffer tunings to sysctl
cat << 'EOF' | sudo tee /etc/sysctl.d/99-caddy-streaming.conf
# Expand maximum and default socket buffer sizes for UDP/QUIC and TCP
net.core.rmem_max = 7500000
net.core.wmem_max = 7500000
net.core.rmem_default = 262144
net.core.wmem_default = 262144

# Optimize UDP memory limits (min, pressure threshold, max pages)
net.ipv4.udp_rmem_min = 16384
net.ipv4.udp_wmem_min = 16384

# Increase backlog queues to absorb connection bursts without SYN/UDP drops
net.core.netdev_max_backlog = 10000
net.core.somaxconn = 8192

# Ensure TCP BBR congestion control remains active for fallback TCP streams
net.core.default_qdisc = fq
net.ipv4.tcp_congestion_control = bbr
EOF

# Load and enforce parameters immediately
sudo sysctl --system

On production KVM instances deployed on tropic.host, the hypervisor ensures unmetered 1–10 Gbps uplinks with TCP BBR enabled by default. Because instances operate with zero CPU steal time (%st = 0.0%), userspace QUIC packet handling in Caddy is never starved of CPU cycles during cryptographic handshake spikes.

Network Architecture: Native Host vs. Containerized Bridge

To achieve minimum latency and eliminate Docker's docker-proxy userspace overhead, run Caddy either directly as a native systemd unit or bind it to host networking within Docker Compose. When containerizing Caddy, pass the UDP port mapping explicitly to enable QUIC alongside standard TCP:

# Add Caddy to /opt/jellyfin/docker-compose.yml as the front-end ingress
services:
  caddy:
    image: caddy:2-alpine
    container_name: caddy
    restart: unless-stopped
    network_mode: host
    volumes:
      - /opt/caddy/Caddyfile:/etc/caddy/Caddyfile:ro
      - /opt/caddy/data:/data
      - /opt/caddy/config:/config
      - /var/log/caddy:/var/log/caddy
    environment:
      - TZ=UTC
    depends_on:
      - jellyfin

Using network_mode: host allows Caddy to communicate with Jellyfin over 127.0.0.1:8096 with sub-millisecond local loopback latency, bypassing iptables NAT traversal and retaining client IP fidelity without requiring complex PROXY protocol handshakes.

Production Caddyfile for Low-Latency Media Streaming

Create the production /opt/caddy/Caddyfile. The configuration implements: 1. Zero-Buffering Proxy Pass: Flushing video stream buffers downstream instantaneously to the client player. 2. Selective MIME Compression: Compressing JSON, JavaScript, and CSS assets via modern algorithms (zstd, gzip) while strictly excluding video streams (.ts, .mp4, .m4s, .mkv), which are already densely compressed and would only waste CPU cycles. 3. Transport Security Hardening: Injecting strict HTTP security headers (HSTS, nosniff, frame protection) while permitting WebSockets for Jellyfin's real-time sync mechanism.

# Global runtime options
{
    admin off
    auto_https disable_redirects
    log {
        output file /var/log/caddy/caddy_runtime.log {
            roll_size 20MiB
            roll_keep 5
        }
        format json
    }
}

# Ingress definition for Jellyfin Edge
media.yourdomain.com {
    # Bind ports explicitly (HTTP/3 runs over UDP 443)
    bind 0.0.0.0

    # Transport-layer and browser security policies
    header {
        Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"
        X-Content-Type-Options "nosniff"
        X-Frame-Options "SAMEORIGIN"
        Referrer-Policy "strict-origin-when-cross-origin"
        Permissions-Policy "accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()"
        -server
    }

    # Compress metadata and web UI assets; bypass media containers
    encode zstd gzip {
        match {
            header Content-Type application/json*
            header Content-Type application/javascript*
            header Content-Type text/*
            header Content-Type image/svg+xml*
        }
    }

    # Upstream routing to Jellyfin Kestrel backend
    reverse_proxy 127.0.0.1:8096 {
        # CRITICAL: Disable response buffering to eliminate TTFB latency on video chunks.
        # -1 forces immediate flushing of each packet from upstream to downstream.
        flush_interval -1

        # Preserve client routing context
        header_up Host {host}
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
        header_up X-Forwarded-Host {host}
        header_up X-Forwarded-Port {server_port}

        # Keepalive timeouts for continuous low-latency upstream connections
        transport http {
            keepalive 120s
            keepalive_idle_conns 100
            dial_timeout 5s
            response_header_timeout 30s
        }
    }

    # Structured JSON access logs for metrics parsing and audit trails
    log {
        output file /var/log/caddy/jellyfin_access.log {
            roll_size 50MiB
            roll_keep 7
            roll_keep_for 168h
        }
        format json
    }
}

# Global HTTP to HTTPS redirection
http://media.yourdomain.com {
    redir https://{host}{uri} permanent
}

Architectural Breakdown of Critical Directives

flush_interval -1: By default, reverse proxies buffer upstream HTTP responses to optimize socket write utilization. In live HLS/fMP4 transcoding or chunked direct-stream playback, buffering delays individual chunks by several hundred milliseconds. Setting flush_interval -1 forces Caddy to emit data chunks the instant they leave Jellyfin's ASP.NET Kestrel web server, dropping p99 Time to First Byte (TTFB) to native NVMe read latencies (< 1.5 ms).
Transparent WebSockets: Jellyfin relies on /socket to maintain a persistent state-sync pipeline for Playback Stop/Pause synchronization, SyncPlay group streaming, and remote client administration. In Caddy, when an incoming request includes Connection: Upgrade and Upgrade: websocket, the proxy engine automatically transitions the transport into a full-duplex TCP tunnel without requiring specialized upstream connection blocks.
MIME Matching in encode: Video streams are high-entropy binary payloads. Passing an H.264 or AV1 bitstream through gzip or zstd yields 0% compression while pegging the CPU at 100% capacity. Restricting encode to text/*, application/json*, and static scripts preserves CPU headroom for hardware/software transcoding tasks.

Firewall Configuration and ACME DNS/ALPN Provisioning

Caddy uses the standard ACME protocol to obtain certificates from Let's Encrypt or ZeroSSL. When running on a cloud instance with a dedicated, unshared IPv4, the tls-alpn-01 and http-01 challenges execute automatically.

Open standard incoming ports on the host firewall (both TCP and UDP for port 443):

# Allow HTTP, HTTPS (TCP), and HTTP/3 / QUIC (UDP) through UFW
sudo ufw allow 80/tcp comment "Caddy ACME HTTP-01"
sudo ufw allow 443/tcp comment "Caddy HTTPS TLS"
sudo ufw allow 443/udp comment "Caddy HTTP/3 QUIC"

# Reload firewall state and audit active rules
sudo ufw reload
sudo ufw status verbose

If utilizing native nftables, add the respective bindings to the inet filter input chain:

add rule inet filter input tcp dport { 80, 443 } ct state new accept
add rule inet filter input udp dport 443 ct state new accept

Because platforms like tropic.host issue clean static IPv4 addresses without ISP port filtration or CGNAT boundaries, ACME challenges pass validation on the first attempt without falling back to complex DNS API tokens.

Runtime Verification and Edge Latency Profiling

Once Caddy is running, execute a validation pipeline to audit TLS negotiation, HTTP/3 readiness, and WebSocket switching.

1. Validate HTTP/3 and ALPN Negotiation

Test the endpoint using curl with HTTP/3 support enabled:

# Inspect protocol negotiation and response headers
curl -IL --http3-only https://media.yourdomain.com/System/Info/Public

The response header must return HTTP/3 200 and include the appropriate security markers:

HTTP/3 200
alt-svc: h3=":443"; ma=2592000
content-type: application/json; charset=utf-8
strict-transport-security: max-age=63072000; includeSubDomains; preload
x-content-type-options: nosniff
x-frame-options: SAMEORIGIN

The presence of the alt-svc header instructs connecting browsers (Chrome, Firefox, Safari) and native Android/iOS media players to upgrade subsequent video slice requests from TCP to UDP-based HTTP/3, eliminating Head-of-Line (HoL) blocking across congested client Wi-Fi or mobile links.

2. Validate WebSocket Protocol Switching

Verify that the bi-directional /socket endpoint upgrades cleanly:

curl -i -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  https://media.yourdomain.com/socket

A healthy response confirms the protocol switch:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

3. Audit p99 Time to First Byte (TTFB) on Chunked Video Reads

Profile the transport layer latency by querying a 1 MB byte-range from a static media asset using a high-precision cURL format template:

# Generate latency profiling format file
cat << 'EOF' > /tmp/curl-format.txt
    time_namelookup:  %{time_namelookup}s\n
       time_connect:  %{time_connect}s\n
    time_appconnect:  %{time_appconnect}s\n
   time_pretransfer:  %{time_pretransfer}s\n
      time_starttransfer:  %{time_starttransfer}s\n
         time_total:  %{time_total}s\n
               speed:  %{speed_download} bytes/s\n
EOF

# Execute byte-range partial content request (simulating video player buffer fetch)
curl -r 0-1048576 -w "@/tmp/curl-format.txt" -o /dev/null -s https://media.yourdomain.com/web/index.html

On correctly sized infrastructure, time_starttransfer (representing the real TTFB) must clock under 15–25 ms over WAN and under 1.8 ms over local network paths, confirming that neither Caddy nor the underlying hypervisor storage subsystem is introducing queuing delay.

Transcoding Profiles: HEVC/H.264, Bitrate Throttling, and Client Apps

Optimizing a Jellyfin media server deployed on a headless VPS requires a strict delivery architecture. Video transcoding is the single most compute-expensive operation a cloud server can execute. On standard KVM instances lacking dedicated PCIe GPU passthrough or Intel QuickSync (QAT/VAAPI) SR-IOV virtual functions, unconstrained software transcoding via libx264 or libsvtav1 will instantly pin all assigned vCPUs to 100%, induce scheduling starvation across the reverse proxy, and exhaust available memory buffers.

The engineering objective when serving media to mobile and TV endpoints is clear: maximize Direct Play and Direct Stream (remuxing) while strictly bounding software transcode execution through in-memory buffer isolation, cgroups v2 CPU quotas, and client-tailored delivery profiles.

1. Delivery Tier Architecture: Direct Play vs. Direct Stream vs. Full Transcode

To allocate server compute efficiently, media delivery must be segmented into three distinct execution paths based on client codec support:

[Raw Container: MKV / MP4] 
         │
         ├─── Direct Play ────────────────────────────────────────► Client
         │    (Container, Video, Audio, Subs match client caps)
         │    Compute: Zero | I/O: Pure zero-copy socket send
         │
         ├─── Direct Stream (Remux) ──────────────────────────────► Client
         │    (Video matches; Container MKV->fMP4 or Audio DTS->AAC)
         │    Compute: < 3% vCPU | I/O: Light demux/mux
         │
         └─── Full Transcode (FFmpeg Decode-Filter-Encode) ───────► Client
              (Video codec mismatch, bitrate capping, or burn-in subs)
              Compute: 400-800% vCPU (Without HW acceleration)

Direct Play: The client's decoder handles the native container (MKV, MP4, WebM), video bitstream (HEVC Main 10, H.264 [email protected]), and audio codec (FLAC, AAC, TrueHD, DTS). The host kernel bypasses user-space transformation entirely, relying on sendfile(2) or HTTP chunked transport via Caddy.
Direct Stream (Remuxing): The video codec is natively supported by the client, but either the audio track requires conversion (e.g., downmixing 7.1 TrueHD to 2.0 AAC-LC for a mobile web browser) or the container must be repackaged (e.g., stripping Matroska .mkv headers into fragmented MP4 .m4s chunks for Safari/iOS HLS). CPU overhead remains negligible (<0.05 vCPU core per stream).
Full Transcode: The host decodes the source video frame-by-frame, runs optional scaling/color-space conversion filters, and re-encodes the stream to H.264 or HEVC using software libraries. This path must be treated as an edge-case fallback and bounded by strict resource quotas.

2. In-Memory Transcode Pipeline and Storage I/O Isolation

When FFmpeg generates HTTP Live Streaming (HLS) streams, it rapidly writes and deletes 3-to-6-second chunked segment files (.ts or .m4s) alongside evolving .m3u8 playlists. Writing this high-frequency, ephemeral data directly to block storage induces severe disk write amplification and exhausts NVMe controller write cycles.

Isolate the transcoding working directory directly into volatile memory using a dedicated tmpfs mount.

Dedicated Tmpfs Mount Configuration

Add the following entry to /etc/fstab on the VPS host:

tmpfs   /var/lib/jellyfin/transcodes   tmpfs   defaults,noatime,nosuid,nodev,size=4G,mode=0755,uid=1000,gid=1000   0 0

Mount the volume immediately and verify allocation:

mkdir -p /var/lib/jellyfin/transcodes
mount /var/lib/jellyfin/transcodes
df -h /var/lib/jellyfin/transcodes

Kernel Virtual Memory Buffer Tuning

Prevent the kernel from aggressive page-cache flushing during burst transcoding by modifying dirty page ratios in /etc/sysctl.d/99-jellyfin-transcode.conf:

# Force background pdflush daemon to start writing at 5% dirty page ratio
vm.dirty_background_ratio = 5
# Block incoming processes from generating dirty pages at 10% ratio
vm.dirty_ratio = 10
# Preserve low watermark pages to ensure immediate allocation for network/transcode buffers
vm.min_free_kbytes = 65536

Apply the parameters immediately:

sysctl --system

On tropic.host KVM VPS instances powered by enterprise PCIe 4.0 NVMe drives, isolating the transcode directory to tmpfs prevents I/O contention entirely. This guarantees that concurrent metadata indexing (SQLite operations) and heavy media read operations sustain over 50,000 random 4K QD1 IOPS without queue degradation.

3. Cgroups v2 Resource Governance and FFmpeg Execution Limits

Without process-level throttling, a single multi-threaded FFmpeg process will spawn nproc * 1.5 threads, monopolizing hypervisor vCPU allocations and inducing latency spikes across edge reverse-proxies.

If deploying Jellyfin via Docker Compose, enforce strict cgroups v2 CPU weight, quota caps, and memory limits within your docker-compose.yml:

version: '3.8'

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    user: "1000:1000"
    restart: unless-stopped
    network_mode: "host"
    environment:
      - JELLYFIN_PublishedServerUrl=https://media.yourdomain.com
    volumes:
      - /opt/jellyfin/config:/config
      - /opt/jellyfin/cache:/cache
      - /var/lib/jellyfin/transcodes:/transcode
      - /mnt/storage/media:/media:ro
    deploy:
      resources:
        limits:
          # Cap Jellyfin to 4 dedicated vCPUs (out of e.g. 6 or 8)
          cpus: '4.00'
          memory: 6144M
        reservations:
          cpus: '1.00'
          memory: 2048M
    # In-memory fast path for transcode chunking if not using host mount
    tmpfs:
      - /transcode:size=4294967296,uid=1000,gid=1000,mode=1777

If operating directly through systemd, configure a resource slice override at /etc/systemd/system/jellyfin.service.d/cgroups.conf:

[Service]
# Set CPU quota to 400% (4 full vCPUs)
CPUAccounting=true
CPUQuota=400%
# Lower scheduling priority relative to Caddy/Nginx (default 100)
CPUWeight=80

# Enforce proactive page reclamation before triggering OOM killer
MemoryAccounting=true
MemoryHigh=5G
MemoryMax=6G

Reload the systemd daemon to commit changes:

systemctl daemon-reload
systemctl restart jellyfin

4. Encoding Profiles and Server-Side Throttling Configuration

Within the Jellyfin Administration Dashboard (Dashboard -> Playback -> Transcoding), apply production settings tuned for VPS CPU constraints:

Transcoding Thread Count: Never leave this set to 0 (Auto) on multi-core hypervisors. Set this to a fixed number matching your reserved cgroups v2 ceiling (e.g., 4). Unchecked thread spawning on AMD EPYC architectures triggers L3 cache thrashing and lock contention.
H.264 Encoding Preset: Configure strictly to veryfast or superfast. In software-only encoding, medium or slow presets consume 300% more CPU cycles for a marginal 4–6% reduction in transport bitrate.
Throttle Transcoding: Check "Enable throttling".
- Mechanism: When active, FFmpeg will transcode until it generates a defined segment buffer (default: 120 seconds ahead of the client's current playback timestamp), then pause (SIGSTOP equivalent execution state). When the client consumes segments and drops below the threshold, the transcoder resumes. This eliminates continuous 100% vCPU consumption for clients pausing or abandoning media.
HLS Segment Duration: Set to 3 seconds (down from the legacy 6-second default). Shorter segments minimize Time-To-First-Frame (TTFF) during seek operations on mobile clients, directly reducing initial request latency.
Segment Format: Enforce fMP4 (Fragmented MP4) over legacy MPEG-TS. Fragmented MP4 carries lower container header overhead and enables seamless HEVC transport over HLS for Apple devices.

# Verify transcode throttle states in runtime logs
journalctl -u jellyfin -f | grep -E "Throttling transcoder|Resuming transcoder"

5. The Subtitle Burn-In Bottleneck: SSA/ASS Mitigation

The most common cause of unexpected server-side CPU exhaustion is subtitle burn-in. When a client requests complex stylized vector subtitles (.ass / .ssa, common in anime) or bitmap-based streams (PGS / VobSub, common on Blu-ray rips), and the client playback engine cannot natively render them, Jellyfin triggers the FFmpeg -filter_complex subtitles=... filter.

This filter forces a full decode, rasters every subtitle glyph onto the uncompressed video frame in CPU memory, and re-encodes the stream. This collapses multi-threading into a single-core bottleneck, causing immediate stream buffering.

Prevention Strategy:

Extract Text Subtitles: Strip or convert PGS/ASS subtitles into standard SubRip (.srt) or WebVTT (.vtt) files using mkvtoolnix or an automated worker: bash # Extract subtitle track 2 from Matroska container to clean UTF-8 SRT mkvextract tracks input_video.mkv 2:subtitles.srt
Enforce Client-Side Extraction: In Jellyfin under Admin -> Dashboard -> Playback, set Allow subtitle extraction on the fly to Enabled. The server extracts plain text on demand, transmitting WebVTT sidecar files directly to mobile and TV players without touching the video pipeline.

6. Client Ecosystem Tuning Matrix

Different client applications present radically different decoding pipelines. Instruct your user base or configure device profiles according to the following matrix:

Client Platform	Recommended Client Engine	Native Video Support	Native Audio Support	Common Transcode Triggers	Configuration Fix
Android TV / Shield	Official Jellyfin Android TV (ExoPlayer)	HEVC 8/10-bit, H.264, VP9, AV1	EAC3, AC3, DTS, TrueHD (Passthrough)	Server-side bitrate limits set lower than video stream	Set In-App Bitrate to `100 Mbps / Maximum` to ensure Direct Play.
Apple TV 4K / iOS	Swiftfin or Jellyfin Mobile (Native Player)	HEVC Main/Main 10, H.264	AAC-LC, ALAC, EAC3-JOC (Dolby Atmos)	Matroska (`.mkv`) container or DTS audio	Configure Swiftfin engine to use libVLC or MPV backend if `.mkv` triggers remux.
Desktop Web (Chromium)	Chrome / Brave / Edge	H.264, VP9, AV1 (HEVC conditional on OS)	AAC, Opus, FLAC	High-profile HEVC 10-bit without OS hardware decoder flag	Switch playback to Jellyfin Media Player (Desktop) to utilize local `mpv` rendering.
Desktop Web (Firefox)	Firefox on Linux/Windows	H.264, VP9, AV1	AAC, Opus, FLAC, Vorbis	HEVC / AC3 / DTS (Lacks proprietary codec licensing)	Audio transcode to AAC is automatically invoked; video Direct Streams.

7. Bitrate Throttling and Network Delivery Profiles

Bitrate limits must be enforced dynamically on the client side rather than by hardcoding destructive transcode limits on the server. If a client sets its playback profile to 3 Mbps - 720p, the server is forced to transcode a pristine 1080p source down to 720p, burning CPU cycles unnecessarily.

Because tropic.host delivers clean, unmetered 1–10 Gbps uplinks with direct BGP peering to core IXPs (Frankfurt, Amsterdam, London, Istanbul, Singapore) and Linux TCP BBR enabled by default, WAN throughput is rarely the true bottleneck.

# Validate active congestion control mechanism on host
sysctl net.ipv4.tcp_congestion_control
# Expected output: net.ipv4.tcp_congestion_control = bbr

By ensuring your VPS environment operates with 0.0% CPU Steal Time (%st = 0.0%) and an uncontended network path, mobile and TV clients can safely set their playback quality to Maximum / Direct Play. The client pulls 40–80 Mbps 4K Remux streams over raw HTTP/3, completely bypassing the VPS transcode engine and eliminating hypervisor load.

Backup Automation and Complete Disaster Recovery Procedure

Operating a production-grade jellyfin media server on vps instances demands an absolute architectural demarcation between immutable container runtimes, read-only bulk media mounts, and volatile, stateful application data. While multi-terabyte media libraries are typically hosted on detached object stores, network file systems, or separate bulk storage arrays, the core operational heartbeat of Jellyfin resides strictly within its configuration root—specifically SQLite databases, XML configuration schemas, cryptographic keyrings, user playback progression markers, and metadata caches.

Failing to isolate and consistently back up these components leads to catastrophic library state corruption or total loss of watch histories during an unrecoverable host failure.

1. State Identification and SQLite WAL Consistency Pitfalls

Inside the Jellyfin data volume (defaulting to /config), state is split across distinct transactional and non-transactional domains:

/config/data/jellyfin.db: Houses global system metadata, user accounts, salted password hashes, permission grants, custom device profiles, and client session records.
/config/data/library.db: The core library catalog containing item identifiers, path resolutions, external metadata mapping (TheTVDB, TheMovieDB), play states, and precise resume timecodes.
/config/config/: Plaintext XML files (system.xml, encoding.xml, network.xml) holding hardware transcode preferences, DLNA toggles, and base HTTP listener bindings.
/config/plugins/: Compiled DLL binaries and individual plugin configuration bundles.

The primary operational failure in naïve backup strategies (such as raw tar or rsync executions across an active /config directory) stems from the SQLite journaling engine. Jellyfin operates SQLite in Write-Ahead Logging mode (PRAGMA journal_mode=WAL;). Under WAL mode, active transactions write modifications to a companion -wal file, synchronized through a shared-memory index file (-shm).

Executing an asynchronous file copy while writes are queued in the WAL file inevitably yields a corrupted, out-of-sync snapshot where the main database file references invalidated b-tree pages. Attempting to restore a database in this split state results in fatal disk I/O errors (SQLITE_CORRUPT: database disk image is malformed) upon boot.

To guarantee zero database corruption without stopping active media streams, you must execute a point-in-time hot backup using SQLite’s native online backup API via the command-line interface.

2. Production Hot-Backup Pipeline Architecture

A resilient backup architecture relies on a deterministic two-stage execution model: 1. Online Transactional Checkpoint & Export: Querying the live database files via the SQLite CLI to produce clean, isolated database dumps with all WAL frames fully flushed. 2. Encrypted, Deduplicated Remote Synchronization: Compacting the database exports and static XML configurations into an encrypted, offsite repository using restic. The volatile transcode directory (/cache/transcodes) and regenerable dynamic caches (/cache/temp) are explicitly excluded to conserve bandwidth and storage IOPS.

flowchart LR
    subgraph Host["VPS Instance (tropic.host)"]
        LiveDB[("Live SQLite WAL\njellyfin.db / library.db")]
        SQLiteAPI["sqlite3 Online Backup API\n(WAL Flush)"]
        Staging[("/var/backups/jellyfin/staging\nClean Consistent Snapshots")]
        ConfigXML["Static Configs\n(/config/config/*.xml)"]
        Restic["Restic Engine\n(Zstandard / AES-256)"]

        LiveDB -->|Hot checkpoint| SQLiteAPI
        SQLiteAPI -->|Atomic export| Staging
        Staging --> Restic
        ConfigXML --> Restic
    end

    subgraph Remote["Offsite Infrastructure"]
        S3[("S3 / B2 Object Storage\nor Secondary KVM VPS")]
    end

    Restic -->|"1-10 Gbps BBR Uplink\nTLS Encrypted Packets"| S3

Step 1: Deploy the Automated Backup Script

Create the core backup orchestration script at /usr/local/bin/jellyfin-backup.sh. This script manages atomic staging, database integrity validation before shipping, encrypted offsite deduplication via restic, and automated retention pruning.

#!/usr/bin/env bash
set -euo pipefail
IFS=$'\n\t'

# ==============================================================================
# JELLYFIN PRODUCTION HOT BACKUP SCRIPT
# ==============================================================================

# Operational Paths
CONFIG_DIR="/opt/jellyfin/config"
STAGING_DIR="/var/backups/jellyfin/staging"
DB_DIR="${CONFIG_DIR}/data"
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")

# Export Restic Environment (Set remote repository target and credentials)
export RESTIC_REPOSITORY="s3:https://s3.eu-central-1.wasabisys.com/infra-backups-jellyfin/repo"
export RESTIC_PASSWORD_FILE="/etc/restic/backup-password.txt"
export AWS_ACCESS_KEY_ID="YOUR_WASABI_OR_B2_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="YOUR_WASABI_OR_B2_SECRET_KEY"

# Ensure runtime directories exist with hardened permissions
mkdir -p "${STAGING_DIR}"
chmod 700 "${STAGING_DIR}"

cleanup() {
    local exit_code=$?
    rm -rf "${STAGING_DIR:?}"/*
    if [ ${exit_code} -ne 0 ]; then
        echo "[ERROR] Jellyfin backup pipeline failed with exit code ${exit_code} at $(date -u)" >&2
    fi
    exit ${exit_code}
}
trap cleanup EXIT INT TERM

echo "[INFO] Commencing online SQLite checkpointing and backup..."

# 1. Hot-backup SQLite databases atomically using SQLite API
for db in "jellyfin.db" "library.db"; do
    if [ -f "${DB_DIR}/${db}" ]; then
        # Enforce WAL checkpoint and stream a point-in-time copy to staging
        sqlite3 "${DB_DIR}/${db}" ".backup '${STAGING_DIR}/${db}'"

        # Immediate validation: Verify integrity of the generated backup artifact
        INTEGRITY_CHECK=$(sqlite3 "${STAGING_DIR}/${db}" "PRAGMA quick_check;")
        if [ "${INTEGRITY_CHECK}" != "ok" ]; then
            echo "[CRITICAL] Staged database ${db} failed PRAGMA quick_check: ${INTEGRITY_CHECK}" >&2
            exit 1
        fi
    fi
done

echo "[INFO] SQLite databases successfully validated. Executing Restic snapshot..."

# 2. Execute encrypted deduplicated offsite snapshot
restic backup \
    --tag "jellyfin-core" \
    --tag "automated" \
    --exclude "${CONFIG_DIR}/cache" \
    --exclude "${CONFIG_DIR}/log" \
    --exclude "${CONFIG_DIR}/transcodes" \
    --exclude "${CONFIG_DIR}/metadata/People" \
    --exclude "${CONFIG_DIR}/data/*.db*" \
    "${CONFIG_DIR}" \
    "${STAGING_DIR}"

echo "[INFO] Backup ingested. Pruning snapshots according to retention policy..."

# 3. Enforce snapshot lifecycle policy (GFS Retention)
restic forget \
    --tag "jellyfin-core" \
    --keep-daily 7 \
    --keep-weekly 4 \
    --keep-monthly 12 \
    --prune

# 4. Light integrity check of repository metadata
restic check --read-data-subset=1%

echo "[SUCCESS] Jellyfin backup completed successfully at $(date -u)"

Lock down script execution permissions:

chmod 700 /usr/local/bin/jellyfin-backup.sh
mkdir -p /etc/restic
echo "YOUR_HIGH_ENTROPY_ENCRYPTION_PASSPHRASE" > /etc/restic/backup-password.txt
chmod 600 /etc/restic/backup-password.txt

Initialize the remote restic repository once prior to scheduling:

restic init

3. Systemd Scheduling and cgroups Resource Isolation

A backup process executing SHA-256 deduplication and Zstandard compression can trigger severe I/O stalls and CPU spikes if left unconstrained, degrading ongoing media transcodes or causing frame drops on active streams.

To protect media server processes from resource starvation, schedule the backup via systemd using explicit cgroups v2 resource throttles (CPUWeight, IOWeight, MemoryMax).

Step 1: Define the Systemd Service Unit

Create /etc/systemd/system/jellyfin-backup.service:

[Unit]
Description=Jellyfin State Hot Backup and Remote Synchronization
Documentation=https://jellyfin.org/docs/
After=network-online.target docker.service
Wants=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/jellyfin-backup.sh

# cgroups v2 Resource Governance
CPUAccounting=true
CPUWeight=100
MemoryAccounting=true
MemoryHigh=1G
MemoryMax=1.5G
IOAccounting=true
IOWeight=100

# Process Scheduling Priorities
Nice=19
IOSchedulingClass=idle
IOSchedulingPriority=7

# Sandboxing and System Hardening
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/var/backups/jellyfin /tmp
PrivateTmp=true
ProtectKernelTunables=true
ProtectControlGroups=true
RestrictRealtime=true

Step 2: Define the Systemd Timer Unit

Create /etc/systemd/system/jellyfin-backup.timer:

[Unit]
Description=Nightly Trigger for Jellyfin Hot Backup Pipeline
Requires=jellyfin-backup.service

[Timer]
OnCalendar=*-*-* 03:30:00 UTC
RandomizedDelaySec=1800
Persistent=true

[Install]
WantedBy=timers.target

Enable and activate the timer:

systemctl daemon-reload
systemctl enable --now jellyfin-backup.timer
systemctl list-timers --all | grep jellyfin-backup

Deploying this pipeline on tropic.host delivers a distinct operational advantage during snapshot generation. The underlying PCIe 4.0 NVMe storage layer provides random 4K QD1 read IOPS exceeding 50,000, keeping SQLite hot-checkpointing disk latency below 0.3 ms (p99 < 0.3ms).

Because host nodes maintain 0.0% CPU Steal Time (%st = 0.0%), the cryptographic hashing phase runs deterministically without hypervisor scheduling contention. Furthermore, the unmetered 1–10 Gbps uplinks with native Linux TCP BBR congestion control allow high-volume restic chunks to saturate remote ingest pipes without queuing or packet jitter.

4. Complete Disaster Recovery (DR) Runbook

In a catastrophic failure event—such as hypervisor failure, filesystem corruption, or ransomware compromise—the following procedure details the exact, bare-metal recovery sequence on a freshly provisioned KVM VPS.

sequenceDiagram
    autonumber
    actor Admin as DevOps Engineer
    participant Host as Fresh Target VPS
    participant Restic as Remote Repository
    participant Jellyfin as Jellyfin Engine

    Admin->>Host: Provision base OS & verify %st = 0.0%
    Admin->>Host: Install Docker, SQLite3 & Restic
    Admin->>Restic: Authenticate via IAM & passphrase
    Restic-->>Host: Stream latest snapshot
    Admin->>Host: Merge staging SQLite copies to /config/data
    Admin->>Host: Execute PRAGMA integrity_check
    Note over Host: Assert result == "ok"
    Admin->>Host: Enforce UID/GID mapping (1000:1000)
    Admin->>Jellyfin: docker compose up -d
    Jellyfin-->>Admin: HTTP 200 OK via /health endpoint

Step 1: Base Environment Preparation

On the freshly deployed VPS (Ubuntu 24.04 LTS / Debian 12), establish the base directory structure and install the required tools:

# Update repositories and install runtime binaries
apt-get update && apt-get install -y --no-install-recommends \
    curl \
    ca-certificates \
    gnupg \
    sqlite3 \
    restic \
    jq

# Prepare application roots
mkdir -p /opt/jellyfin/config /opt/jellyfin/media /etc/restic
chmod 755 /opt/jellyfin

Ensure Docker Engine and the Compose plugin are deployed:

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  tee /etc/apt/sources.list.d/docker.list > /dev/null

apt-get update && apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

Step 2: Secret Reconstitution and Snapshot Ingestion

Inject your repository encryption passphrase into /etc/restic/backup-password.txt and configure your object storage environment variables:

chmod 600 /etc/restic/backup-password.txt

export RESTIC_REPOSITORY="s3:https://s3.eu-central-1.wasabisys.com/infra-backups-jellyfin/repo"
export RESTIC_PASSWORD_FILE="/etc/restic/backup-password.txt"
export AWS_ACCESS_KEY_ID="YOUR_WASABI_OR_B2_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="YOUR_WASABI_OR_B2_SECRET_KEY"

# Identify the latest snapshot identifier
restic snapshots --tag "jellyfin-core" --latest 1

Restore the snapshot directly into a temporary recovery workspace:

mkdir -p /mnt/recovery
restic restore latest \
    --tag "jellyfin-core" \
    --target /mnt/recovery

# Hydrate the static configuration base
cp -a /mnt/recovery/opt/jellyfin/config/* /opt/jellyfin/config/

# Move the consistent, checkpointed SQLite databases from the staging payload
mkdir -p /opt/jellyfin/config/data
cp -f /mnt/recovery/var/backups/jellyfin/staging/jellyfin.db /opt/jellyfin/config/data/
cp -f /mnt/recovery/var/backups/jellyfin/staging/library.db /opt/jellyfin/config/data/

# Flush staging recovery workspace
rm -rf /mnt/recovery

Step 3: Database Structural Integrity Audit

Never start the Jellyfin daemon without verifying that the restored SQLite database headers and page trees survived transport intact:

for db in "jellyfin.db" "library.db"; do
    TARGET_DB="/opt/jellyfin/config/data/${db}"
    echo -n "Checking ${db}... "

    # Check for b-tree damage, misaligned leaf cells, and schema defects
    INTEGRITY_STATUS=$(sqlite3 "${TARGET_DB}" "PRAGMA integrity_check;")
    FK_STATUS=$(sqlite3 "${TARGET_DB}" "PRAGMA foreign_key_check;")

    if [ "${INTEGRITY_STATUS}" = "ok" ] && [ -z "${FK_STATUS}" ]; then
        echo "VALID (Integrity: OK, Foreign Keys: Valid)"
    else
        echo "FAILED"
        echo "[ERROR] Integrity: ${INTEGRITY_STATUS}" >&2
        echo "[ERROR] Foreign Key Violations: ${FK_STATUS}" >&2
        exit 1
    fi
done

Step 4: Permissions Realignment and Docker Orchestration

Jellyfin runs within container boundaries mapped to non-root system users (PUID=1000, PGID=1000). If file ownership on the restored directories defaults to root:root, the process crashes during early startup due to write-permission denials on /config/log.

Execute permission synchronization across the configuration tree:

# Ensure local service user exists
id -u jellyfin &>/dev/null || useradd -u 1000 -U -d /opt/jellyfin -s /usr/sbin/nologin jellyfin

# Enforce explicit ownership
chown -R 1000:1000 /opt/jellyfin/config
find /opt/jellyfin/config -type d -exec chmod 750 {} +
find /opt/jellyfin/config -type f -exec chmod 640 {} +

Reconstruct the production compose.yaml inside /opt/jellyfin:

services:
  jellyfin:
    image: jellyfin/jellyfin:10.9.11
    container_name: jellyfin
    restart: unless-stopped
    user: "1000:1000"
    network_mode: host
    environment:
      - JELLYFIN_PublishedServerUrl=https://stream.yourdomain.com
    volumes:
      - /opt/jellyfin/config:/config:rw
      - /opt/jellyfin/media:/media:ro
      - type: tmpfs
        target: /cache/transcodes
        tmpfs:
          size: 8589934592 # 8GB allocation in RAM
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Bring the application stack up:

cd /opt/jellyfin
docker compose up -d

Step 5: Post-Restore Operational Validation

Validate application state, database responsiveness, and API availability via automated checks:

# 1. Verify container runtime status
docker ps --filter "name=jellyfin" --format "table {{.ID}}\t{{.Status}}\t{{.Ports}}"

# 2. Poll the local HTTP health check endpoint
curl -I --fail --silent --show-error http://127.0.0.1:8096/health || {
    echo "[CRITICAL] Jellyfin failed local health endpoint checks" >&2
    docker logs --tail 50 jellyfin
    exit 1
}

# 3. Query system information through the internal API
SERVER_NAME=$(curl -s http://127.0.0.1:8096/System/Info/Public | jq -r '.ServerName')
SERVER_VERSION=$(curl -s http://127.0.0.1:8096/System/Info/Public | jq -r '.Version')

echo "=========================================================="
echo "DISASTER RECOVERY COMPLETE"
echo "Server Identity : ${SERVER_NAME}"
echo "Running Version : ${SERVER_VERSION}"
echo "Service Status   : HEALTHY (HTTP 200 OK)"
echo "=========================================================="

By following this deterministic procedure, your server returns to an active, production-ready state with complete library and user watch integrity in under five minutes.

Frequently Asked Questions (FAQ)

Can a VPS transcode 4K video without a dedicated GPU?

Yes, modern high-frequency CPU cores (AMD EPYC or Ryzen 9) can perform software 1080p and 4K transcoding via FFmpeg when allocated 4 to 8 vCPU cores without CPU Steal Time.

How much network bandwidth is needed for Jellyfin streaming?

A 1 Gbps unmetered connection with TCP BBR is ideal, enabling multiple simultaneous 4K streams (25–80 Mbps each) without stuttering or bufferbloat.

Back to Blog

Self-Hosting Jellyfin Media Server on a KVM VPS: 4K Transcoding, 1 Gbps Bandwidth, and Docker Setup

Table of Contents

Hardware Sizing and Bandwidth Requirements for 4K Media Streaming

Compute Allocation: Direct Play vs. Software Transcoding

The 4K HDR Tone-Mapping Penalty

Memory Sizing: Buffer Pools, Linux Page Cache, and RAM Transcoding

Transcode-to-RAM via tmpfs

Page Cache Allocation

Storage I/O Profile: QD1 Random Reads and Sequential Streaming

Network Sizing and Burst Profile: Overcoming BDP and Congestion

Network Buffer Optimization: Kernel Tuning for TCP BBR

Hardware Sizing Matrix for Jellyfin on VPS

Production Deployment: Resource Limits and In-Memory Buffer Orchestration

Verifying CPU Steal and System Scheduler Overhead

Network Optimization: TCP BBR and Socket Tuning for Smooth 60 FPS Video

The Problem with Loss-Based Congestion Control (CUBIC)

Tuning the Linux TCP Stack for Media Streaming

Parameter Breakdown

Verifying BBR and Pacing in Production

Container Network Namespaces: Host Mode vs. Bridge Mode

Upstream Network Quality and Peering Considerations

Deploying Jellyfin with Docker Compose and Persistent Storage Mounts

Directory Topology and Storage Architecture

Ephemeral Transcoding: RAM Disk (tmpfs) vs. NVMe Disk

Hardened Production docker-compose.yml

Key Architectural Directives

Deployment and Runtime Verification

Configuring Caddy Reverse Proxy with Automatic HTTPS and WebSockets

Host Kernel Tuning for High-Throughput HTTP/3 (QUIC)

Network Architecture: Native Host vs. Containerized Bridge

Production Caddyfile for Low-Latency Media Streaming

Architectural Breakdown of Critical Directives

Firewall Configuration and ACME DNS/ALPN Provisioning

Runtime Verification and Edge Latency Profiling

1. Validate HTTP/3 and ALPN Negotiation

2. Validate WebSocket Protocol Switching

3. Audit p99 Time to First Byte (TTFB) on Chunked Video Reads

Transcoding Profiles: HEVC/H.264, Bitrate Throttling, and Client Apps

1. Delivery Tier Architecture: Direct Play vs. Direct Stream vs. Full Transcode

2. In-Memory Transcode Pipeline and Storage I/O Isolation

Dedicated Tmpfs Mount Configuration

Kernel Virtual Memory Buffer Tuning

3. Cgroups v2 Resource Governance and FFmpeg Execution Limits

4. Encoding Profiles and Server-Side Throttling Configuration

5. The Subtitle Burn-In Bottleneck: SSA/ASS Mitigation

Prevention Strategy:

6. Client Ecosystem Tuning Matrix

7. Bitrate Throttling and Network Delivery Profiles

Backup Automation and Complete Disaster Recovery Procedure

1. State Identification and SQLite WAL Consistency Pitfalls

2. Production Hot-Backup Pipeline Architecture

Step 1: Deploy the Automated Backup Script

3. Systemd Scheduling and cgroups Resource Isolation

Step 1: Define the Systemd Service Unit

Step 2: Define the Systemd Timer Unit

4. Complete Disaster Recovery (DR) Runbook

Step 1: Base Environment Preparation

Step 2: Secret Reconstitution and Snapshot Ingestion

Step 3: Database Structural Integrity Audit

Step 4: Permissions Realignment and Docker Orchestration

Step 5: Post-Restore Operational Validation

Frequently Asked Questions (FAQ)

Can a VPS transcode 4K video without a dedicated GPU?

How much network bandwidth is needed for Jellyfin streaming?

Transcode-to-RAM via `tmpfs`

Hardened Production `docker-compose.yml`