[PR #353] nvidia-driver: auto-detect host driver version and initialize the volume on start #327

New issue

Open

opened 2026-10-15 12:50:52 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-15 12:50:52 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/games-on-whales/gow/pull/353
Author: @piotrminkina
Created: 8/2/2026
Status: 🔄 Open

Base: master ← Head: feature/nvidia-auto

📝 Commits (2)

6e38893 nvidia-driver: auto provide nvidia driver version from the host and automate initialize volume
02f8499 build-app: allow selecting the default image variant

📊 Changes

3 files changed (+36 additions, -8 deletions)

View changed files

📝 bin/build-app.sh (+5 -5)
📝 images/nvidia-driver/Dockerfile (+7 -3)
➕ images/nvidia-driver/docker-entrypoint.bash (+24 -0)

📄 Description

What

Makes the nvidia-driver image self-sufficient: it now detects the host driver version at build time and populates the driver volume by itself on container start, instead of requiring the user to pass NV_VERSION manually and run a separate one-shot container to seed the volume.

Changes

images/nvidia-driver/Dockerfile

NV_VERSION can now be supplied through a BuildKit secret mounted at /nvidia-version, falling back to the existing ARG NV_VERSION when the secret is absent:
```
RUN --mount=type=secret,id=nvidia-version,target=/nvidia-version \
    NV_VERSION="${NV_VERSION:-$(cat /nvidia-version)}" && \
    ...
```
This lets Compose feed /sys/module/nvidia/version straight from the host, so the image always matches the running kernel driver — no manual version bookkeeping, no drift after a host driver upgrade.
The final stage moves from FROM scratch to FROM nvidia-installer, so the image has a usable runtime for the entrypoint.
Adds docker-entrypoint.bash as ENTRYPOINT.

images/nvidia-driver/docker-entrypoint.bash (new)

Preflight checks — fails fast with an actionable message instead of leaving a silently broken setup:
- nvidia and nvidia_uvm modules are loaded (/proc/modules)
- nvidia_drm has modeset=Y
Volume initialization — clears ${NV_TARGET_DIR} (default /usr/nvidia.init/) and copies the driver tree from ${NV_SOURCE_DIR} (default /usr/nvidia/), so a rebuilt image refreshes the volume rather than layering a new driver over an old one.
exec "$@"

Both directories are overridable via env vars.

bin/build-app.sh (drive-by, needed to build this image locally)

IMAGE_VARIANT now expands with ${2-"-fedora"} instead of ${2:-"-fedora"}, so an explicitly empty second argument selects the variant-less (default) images — images/base/build instead of images/base/build-fedora. Previously '' was silently rewritten back to -fedora, which made the default variant unreachable through this script. Omitting the argument still defaults to -fedora, so existing invocations are unaffected.
```
./bin/build-app.sh steam ''   # gow/base, gow/base-app, gow/steam
./bin/build-app.sh steam      # gow/base-fedora, gow/base-app-fedora, gow/steam-fedora
```

Usage

Intended to run as a Compose init service that Wolf depends on:

services:
  init-nvidia-driver:
    image: gow/nvidia-driver:latest
    build:
      context: https://github.com/games-on-whales/gow.git#master:/images/nvidia-driver/
      secrets:
        - nvidia-version
    pull_policy: build
    volumes:
      - nvidia-driver-vol:/usr/nvidia.init/:rw

  wolf:
    depends_on:
      init-nvidia-driver:
        condition: service_completed_successfully
        restart: true
    # ...

secrets:
  nvidia-version:
    file: /sys/module/nvidia/version

Companion documentation PR in the Wolf repository, which adds the Nvidia (Auto) tab to the Quickstart guide describing this workflow: https://github.com/games-on-whales/wolf/pull/470

The two changes are complementary — this PR provides the mechanism, the Wolf PR documents it. The Compose example in the Wolf docs builds from games-on-whales/gow.git#master, so it only works once this PR is merged.

🤖 Generated with Claude Code

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/games-on-whales/gow/pull/353 **Author:** [@piotrminkina](https://github.com/piotrminkina) **Created:** 8/2/2026 **Status:** 🔄 Open **Base:** `master` ← **Head:** `feature/nvidia-auto` --- ### 📝 Commits (2) - [`6e38893`](https://github.com/games-on-whales/gow/commit/6e3889374c3ab6ad575d894c2ce0ffdc3a8cfaed) nvidia-driver: auto provide nvidia driver version from the host and automate initialize volume - [`02f8499`](https://github.com/games-on-whales/gow/commit/02f84990966960bee522df3462d68ac4960adb29) build-app: allow selecting the default image variant ### 📊 Changes **3 files changed** (+36 additions, -8 deletions) <details> <summary>View changed files</summary> 📝 `bin/build-app.sh` (+5 -5) 📝 `images/nvidia-driver/Dockerfile` (+7 -3) ➕ `images/nvidia-driver/docker-entrypoint.bash` (+24 -0) </details> ### 📄 Description ## What Makes the `nvidia-driver` image self-sufficient: it now detects the host driver version at build time and populates the driver volume by itself on container start, instead of requiring the user to pass `NV_VERSION` manually and run a separate one-shot container to seed the volume. ## Changes **`images/nvidia-driver/Dockerfile`** - `NV_VERSION` can now be supplied through a BuildKit secret mounted at `/nvidia-version`, falling back to the existing `ARG NV_VERSION` when the secret is absent: ```dockerfile RUN --mount=type=secret,id=nvidia-version,target=/nvidia-version \ NV_VERSION="${NV_VERSION:-$(cat /nvidia-version)}" && \ ... ``` This lets Compose feed `/sys/module/nvidia/version` straight from the host, so the image always matches the running kernel driver — no manual version bookkeeping, no drift after a host driver upgrade. - The final stage moves from `FROM scratch` to `FROM nvidia-installer`, so the image has a usable runtime for the entrypoint. - Adds `docker-entrypoint.bash` as `ENTRYPOINT`. **`images/nvidia-driver/docker-entrypoint.bash`** (new) 1. **Preflight checks** — fails fast with an actionable message instead of leaving a silently broken setup: - `nvidia` and `nvidia_uvm` modules are loaded (`/proc/modules`) - `nvidia_drm` has `modeset=Y` 2. **Volume initialization** — clears `${NV_TARGET_DIR}` (default `/usr/nvidia.init/`) and copies the driver tree from `${NV_SOURCE_DIR}` (default `/usr/nvidia/`), so a rebuilt image refreshes the volume rather than layering a new driver over an old one. 3. `exec "$@"` Both directories are overridable via env vars. **`bin/build-app.sh`** (drive-by, needed to build this image locally) - `IMAGE_VARIANT` now expands with `${2-"-fedora"}` instead of `${2:-"-fedora"}`, so an explicitly empty second argument selects the variant-less (default) images — `images/base/build` instead of `images/base/build-fedora`. Previously `''` was silently rewritten back to `-fedora`, which made the default variant unreachable through this script. Omitting the argument still defaults to `-fedora`, so existing invocations are unaffected. ```console ./bin/build-app.sh steam '' # gow/base, gow/base-app, gow/steam ./bin/build-app.sh steam # gow/base-fedora, gow/base-app-fedora, gow/steam-fedora ``` ## Usage Intended to run as a Compose init service that Wolf depends on: ```yaml services: init-nvidia-driver: image: gow/nvidia-driver:latest build: context: https://github.com/games-on-whales/gow.git#master:/images/nvidia-driver/ secrets: - nvidia-version pull_policy: build volumes: - nvidia-driver-vol:/usr/nvidia.init/:rw wolf: depends_on: init-nvidia-driver: condition: service_completed_successfully restart: true # ... secrets: nvidia-version: file: /sys/module/nvidia/version ``` ## Related Companion documentation PR in the Wolf repository, which adds the **Nvidia (Auto)** tab to the Quickstart guide describing this workflow: https://github.com/games-on-whales/wolf/pull/470 The two changes are complementary — this PR provides the mechanism, the Wolf PR documents it. The Compose example in the Wolf docs builds from `games-on-whales/gow.git#master`, so it only works once this PR is merged. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi added the

pull-request

label

2026-10-15 12:50:52 +00:00