Building a 4K Media Server with Raspberry Pi 5: Hardware, Docker, and Debugging

If you want to build a reliable, low-power 4K media server with Raspberry Pi, the only viable path in 2026 is using the Raspberry Pi 5 (8GB variant) paired with an NVMe drive via the official M.2 HAT+. The Pi 5’s RP1 southbridge and VideoCore VII GPU finally provide the PCIe bandwidth and hardware decoding needed to serve multiple 4K HEVC streams without stuttering. This guide gives you the exact hardware BOM, the FPC pin mappings, a production-ready Docker deployment script, and the specific error strings you will encounter when the silicon pushes back.

Hardware BOM and Performance Specs

Do not attempt this build with a Pi 4 or a microSD card. The I/O bottleneck will ruin the experience. Below is the exact bill of materials required for a stable, 24/7 media server capable of saturating a gigabit LAN connection while transcoding.

Storage & GPIO/Pin Mapping for the M.2 HAT+

The official M.2 HAT+ connects to the Pi 5 via a dedicated 40-pin FPC (Flexible Printed Circuit) connector, not the standard GPIO header. However, it also requires specific 40-pin header jumpers for power and I2C fan control if you are using an active cooler. Here is the exact pin mapping you need to verify during assembly.

Automated Docker Setup Script (Targeting Pi 5 8GB)

This bash script is explicitly written for the Raspberry Pi 5 8GB running Raspberry Pi OS (64-bit, Bookworm or later). It installs Docker, configures the Jellyfin media server with hardware acceleration mapped directly to the VideoCore VII render nodes (/dev/dri), and sets up persistent storage.

#!/bin/bash
# Jellyfin Media Server Setup for Raspberry Pi 5 (8GB)
# Must be run as root or with sudo

set -e

MEDIA_DIR="/mnt/media"
CONFIG_DIR="/opt/jellyfin/config"
CACHE_DIR="/opt/jellyfin/cache"

echo "[1/5] Verifying Pi 5 Hardware and 64-bit OS..."
if [ "$(uname -m)" != "aarch64" ]; then
    echo "ERROR: 64-bit OS required for hardware transcoding."
    exit 1
fi

echo "[2/5] Creating persistent directories..."
mkdir -p $MEDIA_DIR $CONFIG_DIR $CACHE_DIR
chown -R 1000:1000 $CONFIG_DIR $CACHE_DIR

echo "[3/5] Installing Docker and Docker Compose..."
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
rm get-docker.sh

echo "[4/5] Verifying /dev/dri render nodes for Hardware Acceleration..."
if [ ! -e /dev/dri/renderD128 ]; then
    echo "ERROR: GPU render node not found. Check vc4-kms-v3d-pi5 overlay in config.txt."
    exit 1
fi

echo "[5/5] Deploying Jellyfin Container..."
cat <<EOF > /opt/jellyfin/docker-compose.yml
version: '3.8'
services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    user: 1000:1000
    network_mode: 'host'
    volumes:
      - $CONFIG_DIR:/config
      - $CACHE_DIR:/cache
      - $MEDIA_DIR:/media:ro
    devices:
      - /dev/dri/renderD128:/dev/dri/renderD128
      - /dev/dri/card0:/dev/dri/card0
    restart: unless-stopped
EOF

cd /opt/jellyfin
docker compose up -d

echo "Setup complete. Access server at http://$(hostname -I | awk '{print $1}'):8096"
echo "Go to Dashboard > Playback > Transcoding and select 'Video Acceleration API (VAAPI)'"

Debugging: Exact Error Strings and Ranked Causes

When a Pi media server fails, it is almost always a power negotiation issue, a PCIe link dropout, or a Docker permission mapping error. Here are the first three things to check when the system hangs or streams stutter:

1. Power Negotiation: Run dmesg | grep -i power. If it says "5A power supply not detected", the Pi restricts USB/PCIe current to 600mA. Your NVMe drive will brownout under load.
2. PCIe Link Speed: Run lspci -vv | grep LnkSta. If it shows Speed 5GT/s instead of 8GT/s, your Gen 3.0 config tweak failed or the FPC cable is damaged.
3. Render Node Permissions: Run ls -l /dev/dri. If the Docker container runs as UID 1000 but the render node is owned by root:render, hardware acceleration will silently fail.

Ranked Troubleshooting Matrix

Extending or Simplifying the Build

Not every build needs NVMe speeds or Docker orchestration. Here is how to scale this project based on your actual needs and budget.

How to Simplify (The Budget Build)

If you are only serving direct-play 1080p streams to a single TV and want to cut costs by $140:

• Drop the NVMe: Boot from a 32GB A2-rated microSD card.
• Use USB Storage: Plug a 2TB Samsung T7 Shield USB 3.2 SSD directly into the blue USB 3.0 port. The Pi 5’s RP1 chip handles USB mass storage much more efficiently than the Pi 4, easily saturating the 5Gbps link without CPU overhead.
• Skip Docker: Install Jellyfin directly via the official Debian repository (curl -s https://repo.jellyfin.org/install-debuntu.sh | sudo bash). This removes the Docker daemon overhead, freeing up ~300MB of RAM for the OS.

How to Extend (The NAS / Homelab Build)

If you want to turn this media server into a full homelab node:

• Add a UPS HAT: Power outages corrupt NVMe filesystems. Add a Raspberry Pi UPS HAT or a Geekworm X735 to provide clean shutdown signals via I2C when mains power drops.
• Network Attached Storage (NAS) HAT: If you need more than 2TB, stack a 5-bay SATA HAT (like the Radxa Penta SATA HAT) on the GPIO header. You will need to power the Pi 5 via the HAT’s DC barrel jack, as the USB-C PD port cannot supply the 12V/5A required to spin up mechanical hard drives.
• Automated Transcoding Pipeline: Deploy a second Docker container running Tdarr. Point it at your media directory to automatically detect H.264 files and transcode them to H.265 using the Pi 5’s hardware encoder, saving massive amounts of disk space over time.

Building a media server with Raspberry Pi hardware is no longer a compromise. By respecting the PCIe power limits, mapping the render nodes correctly, and avoiding the AV1 trap, the Pi 5 8GB is a genuine, silent, low-wattage replacement for a bulky Intel NUC media server.