Building an OpenMediaVault Server with Jellyfin & Hardware Transcoding

Managing reliable media storage and streaming requires a solid, low-overhead foundation. OpenMediaVault (OMV) provides an exceptional Debian-based NAS platform, and pairing it with Jellyfin running in Docker allows you to stream local media efficiently across your network.

This guide walks through configuring shared folders in OMV, deploying Jellyfin via Docker/Compose, and passing through hardware acceleration (such as Intel QuickSync) for seamless on-the-fly transcoding without choking your CPU.

Part 1: OpenMediaVault Storage Setup

Before spinning up containers, your storage pools need to be mounted and exposed as shared folders.

1. Mount Disks & Create File Systems

1. Log into the OMV Web GUI.
2. Go to Storage > Disks, select your drive, and wipe/initialize it if brand new.
3. Navigate to Storage > File Systems and create an ext4 or XFS file system on your data drive. Mount the file system once created.

2. Create Shared Folders

1. Go to Storage > Shared Folders and click + (Create).
2. Name your folder (e.g., media), select your mounted file system, and set relative paths (e.g., /media/).
3. Set appropriate permissions under Access Control Management to ensure your user or container PUID/PGID has read/write access.

Part 2: Deploying Jellyfin with Docker Compose

Running Jellyfin inside a container ensures easy updates and isolation. To leverage hardware transcoding, you must map the host’s graphics render device straight into the container.

Sample docker-compose.yml Configuration:

 1version: "3.8"
 2
 3services:
 4  jellyfin:
 5    image: jellyfin/jellyfin:latest
 6    container_name: jellyfin
 7    restart: unless-stopped
 8    environment:
 9      - PUID=1000
10      - PGID=1000
11      - TZ=America/Chicago
12    volumes:
13      - /srv/dev-disk-by-uuid-YOUR-UUID/config/jellyfin:/config
14      - /srv/dev-disk-by-uuid-YOUR-UUID/media:/media
15    ports:
16      - 8096:8096
17    devices:
18      # Pass through Intel QuickSync / GPU render nodes to container
19      - /dev/dri/renderD128:/dev/dri/renderD128
20      - /dev/dri/card0:/dev/dri/card0
21    security_opt:
22      - no-new-privileges:true

*Note on Device Paths: Run ls -l /dev/dri on your OMV host via SSH to confirm your render node names (renderD128 is standard for Intel integrated graphics).

Part 3: Enabling Hardware Transcoding in Jellyfin

Once your container is running and accessible on port 8096, configure Jellyfin to offload video processing to your CPU’s integrated graphics:

Open your Jellyfin web dashboard and log in as an administrator.

Go to Dashboard > Server > Playback and click on Transcoding.

Set Hardware acceleration to your platform’s API:

Select Intel QuickSync (QSV) if you are running an Intel processor with QuickSync support.

Check the boxes for the codec formats your hardware supports (e.g., H.264, HEVC, VP9, etc.).

Ensure Enable hardware decoding for [codec] is checked.

Click Save.

Best Practices

Keep Media Read-Only for Users Where Possible: Protect your master media library files by setting appropriate POSIX permissions so regular network shares can read them, but only your downloader/management containers have write access.

Monitor Transcode Sessions: Use intel_gpu_top (installable via apt install intel-gpu-top on the host) to verify that your hardware encoder is actively bearing the load when streaming compressed or incompatible formats.

Common Pitfalls

Permission Denied on /dev/dri/: If Jellyfin throws errors when trying to hardware-transcode, check that the user running Docker has access to the video group, or ensure the device pass-through lines (/dev/dri/…) are explicitly defined under devices: in your compose file.

CPU Bottlenecking: If QuickSync isn’t correctly hooked up, Jellyfin will fall back to software libx264 decoding/encoding, which will quickly spike CPU utilization to 100% on high-bitrate streams.