polish: clean Dockerfile, add README and CLAUDE.md

- Dockerfile: remove ENV misuse, use ARG for build flags, separate
  cmake --build / --install, clean multi-stage layout
- README.md: full background on RELR root cause, usage snippet,
  version update instructions, compatibility table
- CLAUDE.md: critical invariants, consumer reference, testing notes

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: thadamski

CLAUDE.md

@@ -0,0 +1,29 @@
+# plex-vaapi-driver
+
+Builds and publishes `ghcr.io/thadamski/plex-vaapi-driver` — a RELR-free Intel iHD VA-API driver for Plex Media Server.
+
+## What this repo does
+
+Plex ships musl < 1.2.3, which does not process RELR (`.relr.dyn`) sections. Alpine's modern toolchain emits RELR by default. This repo builds `intel-media-driver` and `intel-gmmlib` from source without RELR so Plex's musl can load them.
+
+## Critical invariants
+
+**Do not remove `-Wl,-z,nopackrelocs`** from `LDFLAGS` in the Dockerfile. That flag is the entire reason this image exists.
+
+**Do not remove `-static-libstdc++ -static-libgcc`** from `LDFLAGS`. Alpine's `libstdc++.so` and `libgcc_s.so` also carry RELR — removing the static link reintroduces the crash through the C++ runtime dependencies.
+
+## Updating driver versions
+
+Change `ARG IHD_TAG` and `ARG GMM_TAG` at the top of `Dockerfile` and push to `main`. The workflow rebuilds automatically and pushes `:latest` plus a version-pinned tag.
+
+Tag format:
+- `intel/media-driver` → `intel-media-X.Y.Z`
+- `intel/gmmlib` → `intel-gmmlib-X.Y.Z`
+
+## Consumer
+
+This image is consumed by the private repo `thadamski/homelab-fleet` in `apps/media/plex.yaml` as a Kubernetes init container.
+
+## Testing a new build
+
+After rolling the Plex pod with a new image version, confirm hardware transcoding is active by starting a transcode in Plex and checking that the Plex dashboard shows "hw" next to the stream, or inspect `/var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Logs/` for VA-API initialisation messages.

Dockerfile

@@ -1,45 +1,60 @@
 ARG IHD_TAG=intel-media-26.1.6
 ARG GMM_TAG=intel-gmmlib-22.10.0
 
+# ── Builder ───────────────────────────────────────────────────────────────────
 FROM alpine:latest AS builder
 ARG IHD_TAG
 ARG GMM_TAG
 
-RUN apk add --no-cache alpine-sdk cmake libva-dev libdrm-dev libpciaccess-dev git patchelf
+RUN apk add --no-cache \
+      alpine-sdk \
+      cmake \
+      git \
+      libdrm-dev \
+      libpciaccess-dev \
+      libva-dev \
+      patchelf
 
-# Build without RELR (packed relative relocations) and with static C++ runtime.
-# Plex's bundled musl is pre-1.2.3 and silently skips .relr.dyn sections, leaving
-# .init_array entries unrelocated → SIGSEGV at raw file offset 0x4310.
-ENV LF="-Wl,-z,nopackrelocs -static-libstdc++ -static-libgcc"
+# Plex ships musl < 1.2.3, which silently skips RELR (.relr.dyn) sections when
+# loading shared libraries. Unrelocated .init_array entries cause a segfault on
+# the first constructor call. Both flags are required on every target in this
+# build: -z,nopackrelocs suppresses RELR output; -static-libstdc++ and
+# -static-libgcc eliminate the C++ runtime .so dependencies, which also carry
+# RELR in current Alpine toolchain builds.
+ARG LDFLAGS="-Wl,-z,nopackrelocs -static-libstdc++ -static-libgcc"
 
 RUN git clone --depth=1 --branch "${GMM_TAG}" \
-      https://github.com/intel/gmmlib /tmp/gmmlib && \
-    cmake -S /tmp/gmmlib -B /tmp/gmmlib/build \
-      -DCMAKE_BUILD_TYPE=Release \
-      -DCMAKE_INSTALL_PREFIX=/tmp/sdk \
-      -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
-      -DCMAKE_SHARED_LINKER_FLAGS="${LF}" \
-      -DCMAKE_EXE_LINKER_FLAGS="${LF}" && \
-    cmake --build /tmp/gmmlib/build --target install -- -j$(nproc)
+        https://github.com/intel/gmmlib /src/gmmlib \
+ && cmake -S /src/gmmlib -B /build/gmmlib \
+        -DCMAKE_BUILD_TYPE=Release \
+        -DCMAKE_INSTALL_PREFIX=/sdk \
+        -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
+        "-DCMAKE_SHARED_LINKER_FLAGS=${LDFLAGS}" \
+        "-DCMAKE_EXE_LINKER_FLAGS=${LDFLAGS}" \
+ && cmake --build /build/gmmlib -j$(nproc) \
+ && cmake --install /build/gmmlib
 
 RUN git clone --depth=1 --branch "${IHD_TAG}" \
-      https://github.com/intel/media-driver /tmp/ihd && \
-    cmake -S /tmp/ihd -B /tmp/ihd/build \
-      -DCMAKE_BUILD_TYPE=Release \
-      -DCMAKE_PREFIX_PATH=/tmp/sdk \
-      -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
-      -DBUILD_TESTING=OFF \
-      -DMEDIA_RUN_TEST_SUITE=OFF \
-      -DCMAKE_SHARED_LINKER_FLAGS="${LF}" \
-      -DCMAKE_EXE_LINKER_FLAGS="${LF}" && \
-    cmake --build /tmp/ihd/build --target iHD_drv_video -- -j$(nproc)
+        https://github.com/intel/media-driver /src/ihd \
+ && cmake -S /src/ihd -B /build/ihd \
+        -DCMAKE_BUILD_TYPE=Release \
+        -DCMAKE_INSTALL_PREFIX=/sdk \
+        -DCMAKE_PREFIX_PATH=/sdk \
+        -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
+        -DBUILD_TESTING=OFF \
+        -DMEDIA_RUN_TEST_SUITE=OFF \
+        "-DCMAKE_SHARED_LINKER_FLAGS=${LDFLAGS}" \
+        "-DCMAKE_EXE_LINKER_FLAGS=${LDFLAGS}" \
+ && cmake --build /build/ihd --target iHD_drv_video -j$(nproc)
 
-RUN mkdir -p /opt/vaapi && \
-    cp "$(find /tmp/ihd/build -name iHD_drv_video.so | head -1)" /opt/vaapi/ && \
-    cp -P /tmp/sdk/lib/libigdgmm.so* /opt/vaapi/ && \
-    patchelf --set-rpath /vaapi:/usr/lib/plexmediaserver/lib /opt/vaapi/iHD_drv_video.so && \
-    patchelf --set-rpath /vaapi:/usr/lib/plexmediaserver/lib \
-      /opt/vaapi/libigdgmm.so.12 2>/dev/null || true
+# Set RPATH so iHD resolves libva + libdrm from Plex's lib directory at
+# runtime, and libigdgmm from the /vaapi volume populated by this image.
+RUN install -d /out \
+ && cp "$(find /build/ihd -name iHD_drv_video.so -print -quit)" /out/ \
+ && cp -P /sdk/lib/libigdgmm.so* /out/ \
+ && patchelf --set-rpath '/vaapi:/usr/lib/plexmediaserver/lib' /out/iHD_drv_video.so \
+ && patchelf --set-rpath '/vaapi:/usr/lib/plexmediaserver/lib' /out/libigdgmm.so.12
 
+# ── Runtime image ─────────────────────────────────────────────────────────────
 FROM alpine:latest
-COPY --from=builder /opt/vaapi/ /opt/vaapi/
+COPY --from=builder /out/ /opt/vaapi/

README.md

@@ -0,0 +1,97 @@
+# plex-vaapi-driver
+
+[![Build](https://github.com/thadamski/plex-vaapi-driver/actions/workflows/build.yml/badge.svg)](https://github.com/thadamski/plex-vaapi-driver/actions/workflows/build.yml)
+
+Container image providing an Intel iHD VA-API driver compatible with Plex Media Server's bundled musl runtime on Intel Arc / Xe / i915 hardware.
+
+```
+ghcr.io/thadamski/plex-vaapi-driver:latest
+```
+
+---
+
+## Background
+
+Plex Media Server ships its own musl libc as the dynamic linker for its binaries. This musl build predates version 1.2.3 (released March 2022), which introduced support for [RELR](https://maskray.me/blog/2021-10-31-relative-relocations-and-relr) — a compact encoding for relative relocations (`SHT_RELR` / `.relr.dyn`) that modern toolchains now emit by default.
+
+When Plex's musl loads a shared library that contains a `.relr.dyn` section, it silently skips those relocations. The affected entries in `.init_array` retain their raw link-time file offsets rather than resolved absolute addresses. The dynamic linker then calls that offset value as a function pointer, immediately faulting.
+
+Alpine's pre-built `intel-media-driver` package — and every one of its transitive C++ dependencies — carries `.relr.dyn` sections. This image builds both `intel-media-driver` and `intel-gmmlib` from source with two required flags:
+
+- **`-Wl,-z,nopackrelocs`** — instructs the linker to emit standard `R_X86_64_RELATIVE` entries instead of RELR
+- **`-static-libstdc++ -static-libgcc`** — statically links the C++ runtime, eliminating `libstdc++.so` and `libgcc_s.so` as runtime dependencies (both also carry RELR in current Alpine builds)
+
+The resulting libraries are patched with an RPATH of `/vaapi:/usr/lib/plexmediaserver/lib` so that `iHD_drv_video.so` resolves `libigdgmm` from the shared volume and `libva` / `libdrm` from Plex's own lib directory — with no system libraries involved.
+
+> **Note on `VADriverVTable`:** Plex's `libva.so.2` is often described as having a patched VA-API struct layout. Disassembly of both Plex's and Alpine's libva confirms their `VADriverVTable` and `VADriverContext` layouts are identical. The driver built here is compiled against Alpine's standard `libva-dev` headers and is fully compatible with Plex's runtime.
+
+---
+
+## Usage
+
+Deploy as a Kubernetes init container. It copies the pre-built driver files into a shared `emptyDir` volume before the Plex container starts.
+
+```yaml
+initContainers:
+  - name: vaapi-driver
+    image: ghcr.io/thadamski/plex-vaapi-driver:latest
+    command: ["sh", "-c", "cp -aP /opt/vaapi/. /vaapi/"]
+    volumeMounts:
+      - name: vaapi-driver
+        mountPath: /vaapi
+
+containers:
+  - name: plex
+    env:
+      - name: LIBVA_DRIVER_NAME
+        value: iHD
+      - name: LIBVA_DRIVERS_PATH
+        value: /vaapi
+    resources:
+      limits:
+        gpu.intel.com/i915: "1"
+    volumeMounts:
+      - name: vaapi-driver
+        mountPath: /vaapi
+
+volumes:
+  - name: vaapi-driver
+    emptyDir: {}
+```
+
+The Intel GPU device plugin must be running on the node to expose the `gpu.intel.com/i915` resource. Pods accessing `/dev/dri` also require render group membership (typically GID `991`), set via `securityContext.supplementalGroups`.
+
+---
+
+## Updating versions
+
+Driver versions are defined as `ARG` defaults at the top of the `Dockerfile`.
+
+1. Find the latest releases: [intel/media-driver](https://github.com/intel/media-driver/releases) · [intel/gmmlib](https://github.com/intel/gmmlib/releases)
+2. Update `IHD_TAG` and `GMM_TAG` in `Dockerfile`
+3. Push to `main` — CI rebuilds and publishes both `:latest` and a version-pinned tag
+
+---
+
+## Building locally
+
+```bash
+docker build -t plex-vaapi-driver .
+
+# Override versions
+docker build \
+  --build-arg IHD_TAG=intel-media-26.1.6 \
+  --build-arg GMM_TAG=intel-gmmlib-22.10.0 \
+  -t plex-vaapi-driver .
+```
+
+---
+
+## Compatibility
+
+| Component | Version |
+|-----------|---------|
+| intel-media-driver | 26.1.6 |
+| intel-gmmlib | 22.10.0 |
+| Target GPU | Intel Arc / Xe2 (Arrow Lake) — compatible with Broadwell and newer |
+| Tested with | Plex Media Server 1.43.x, `linuxserver/plex:latest` |