docs(docker): add opt-in GPU runtime image path (#3243)

[rodboev]

Thinking Path

• GPU users need user-space acceleration libraries and device mapping guidance, but most WebUI users should not pay default image-size cost.
• The maintainer explicitly preferred an opt-in build arg or separate GPU Dockerfile rather than installing GPU packages unconditionally.
• This PR keeps CPU-only defaults intact and adds a documented GPU build/runtime path.

What Changed

• Dockerfile: add an opt-in GPU package install path guarded by a build arg.
• docker_init.bash: preserve Docker-provided supplemental groups before dropping to the hermeswebui runtime user, so /dev/dri group access survives startup.
• docs/docker.md: document GPU image build, Intel/AMD /dev/dri mapping, NVIDIA host runtime prerequisites, and verification caveats.
• CHANGELOG.md: add an Unreleased note for the optional GPU image path.
• tests/test_docker_gpu_runtime_docs.py: add static coverage for the opt-in behavior and docs.

Why It Matters

Users running media or inference workloads in containers get a supported starting point without bloating or changing the default image for everyone else.

Verification

python -m pytest tests/test_docker_gpu_runtime_docs.py -q --timeout=60
bash -n docker_init.bash
python scripts/ruff_lint.py --diff origin/master
git diff --check origin/master...HEAD

If Docker is available:

docker build --build-arg INSTALL_GPU_LIBS=1 -t hermes-webui:gpu-smoke .

Risks / Follow-ups

• Hardware passthrough cannot be honestly verified from this Windows workspace unless run on a Linux Docker host with Intel/AMD/NVIDIA devices. The PR should state docs/build verification only if native hardware is not tested.

Model Used

GPT-5.5 via Codex CLI; implementation and adversarial review assisted by Codex/Claude agents.

[greptile-apps]

Greptile Summary

This PR adds an opt-in GPU runtime image path: a INSTALL_GPU_LIBS=1 build arg installs VA-API user-space libraries, docker_init.bash maps Docker-provided supplemental GIDs before dropping to the unprivileged user, and docs/docker.md documents the build command and Intel/AMD/NVIDIA passthrough patterns.

• Dockerfile: new opt-in ARG INSTALL_GPU_LIBS=0 block installs libva2, vainfo, mesa-va-drivers, and optionally intel-media-va-driver-non-free; the CPU-only default is unchanged.
• docker_init.bash: new GID loop runs during the root init phase to ensure Docker --group-add supplemental groups survive the su privilege drop and remain accessible to hermeswebui.
• tests/test_docker_gpu_runtime_docs.py: static doc/config coverage tests; one assertion hard-codes the invalid gpus: all Compose key, making it impossible to fix the docs without also updating the test.

Confidence Score: 3/5

The Compose NVIDIA snippet uses an unrecognized service-level key that Docker will silently ignore, and the test suite asserts that key's presence — locking in the incorrect guidance and blocking a doc fix.

The gpus: all key in the Compose NVIDIA example is not recognized by Docker Compose at the service level, so any user who copies it will find that nvidia-smi still fails inside the container with no useful error. More critically, test_docker_docs_cover_nvidia_host_runtime_guidance asserts "gpus: all" in docker_docs, which ties the test suite to the wrong value and would fail if the docs were corrected to deploy.resources.reservations.devices. These two issues together mean the incorrect guidance is both published and test-protected.

docs/docker.md (NVIDIA Compose snippet) and tests/test_docker_gpu_runtime_docs.py (assertion that hard-codes the invalid key) need to be updated together before this is safe to merge.

Important Files Changed

Filename	Overview
Dockerfile	Adds an ARG INSTALL_GPU_LIBS=0 opt-in block that installs VA-API libraries only when the build arg is set; CPU-only default is preserved and cache cleanup is correct.
docker_init.bash	New loop maps Docker supplemental GIDs to named groups before su; logic is sound but contains a redundant if [ -n "$group_name" ] guard after an unconditional continue on the empty-name path.
docs/docker.md	Adds GPU build/runtime documentation; the Compose NVIDIA snippet uses gpus: all which is not a valid service-level key in Docker Compose (previously flagged).
tests/test_docker_gpu_runtime_docs.py	New static coverage tests; test_docker_docs_cover_nvidia_host_runtime_guidance asserts the invalid gpus: all Compose key, which will break if the docs are corrected.
CHANGELOG.md	Adds an Unreleased entry for the optional GPU image path; correctly placed and accurately describes the change.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[docker build] -->|INSTALL_GPU_LIBS=0 default| B[CPU-only image]
    A -->|INSTALL_GPU_LIBS=1| C[GPU image\nlibva2 + vainfo + mesa-va-drivers\n+ intel-media-va-driver-non-free?]

    D[Container starts as root] --> E{Loop: id -G supplemental GIDs}
    E -->|GID=0 or WANTED_GID| F[skip]
    E -->|known GID| G[getent group → group_name]
    E -->|unknown GID| H[groupadd hostgpu<N>]
    H --> G
    G -->|found| I[usermod -a -G group_name hermeswebui]
    G -->|still empty| J[WARNING: GPU device access may be unavailable]
    I --> K[exec su → hermeswebui]
    J --> K
    K --> L[WebUI process with /dev/dri access preserved]

Loading

_{Reviews (2): Last reviewed commit: "test(docker): defer GPU docs fixture rea..." | Re-trigger Greptile}