Document minimal Nvidia support for base images

[Copilot]

Overview

This PR implements documentation and tooling to add Nvidia driver support to custom bootc images, addressing the deprecation of Universal Blue's dedicated -nvidia images following the community vote in #927.

Users previously relying on ublue-os/*-nvidia base images can now add Nvidia support to any base image using the method documented here.

Changes

New Files

• build_files/nvidia-install.sh - Main script that installs Nvidia drivers from akmods repositories. This script mirrors the implementation from ublue-os/main and:

  • Installs Nvidia driver packages and kernel modules
  • Removes conflicting packages (nvidia-gpu-firmware, ROCm)
  • Configures proper kernel module loading and initramfs
  • Sets up supergfxctl for KDE/GNOME environments

• build_files/ghcurl - Helper script for authenticated GitHub API requests to avoid rate limiting during builds

• Containerfile.nvidia - Complete working example demonstrating how to add Nvidia drivers to any base image, including:

  • Proper build argument configuration
  • Multi-stage build importing nvidia akmods
  • Conflict package removal
  • Driver installation

• build_files/README.md - Documentation explaining all build scripts and their purpose

Updated Files

• README.md - Added comprehensive "Adding Nvidia Driver Support" section with:

  • Context on the -nvidia image deprecation
  • Two implementation options (use example or modify existing Containerfile)
  • Step-by-step instructions with code examples
  • Important notes about kernel versions, flavors, and IMAGE_NAME
  • Instructions for detecting kernel versions in base images
  • Troubleshooting guidance for common issues

• Containerfile - Updated comments to reference the Nvidia example

Implementation Details

The implementation follows the same approach used by ublue-os/bazzite and other Universal Blue projects:

1. Import akmods-nvidia - Uses pre-compiled kernel modules from ghcr.io/ublue-os/akmods-nvidia
2. Remove conflicts - Cleans up packages that conflict with Nvidia drivers
3. Install drivers - Downloads and runs the nvidia-install.sh script from ublue-os/main
4. Configure system - Sets up proper kernel module loading and GPU management tools

Usage Example

Users can now add Nvidia support by using the example Containerfile:

# Import nvidia akmods for your kernel
FROM ghcr.io/ublue-os/akmods-nvidia:${KERNEL_FLAVOR}-${FEDORA_VERSION}-${KERNEL_VERSION} AS nvidia-akmods

# Your base image and customizations
FROM ghcr.io/ublue-os/bazzite:stable AS base
# ... your modifications ...

# Add nvidia stage
FROM base AS nvidia
# Install Nvidia drivers
RUN --mount=type=bind,from=nvidia-akmods,src=/rpms,dst=/tmp/akmods-rpms \
    /ctx/nvidia-install.sh

Testing

• All scripts are syntactically valid (verified with bash -n)
• Implementation matches the pattern used by bazzite's nvidia builds
• Documentation provides clear troubleshooting steps

Fixes #[issue_number]

Refs: ublue-os/main#927 (comment)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Document minimal Nvidia support for base images</issue_title>
<issue_description>Universal Blue's Nvidia builds—the ublue-os/*-nvidia images—are now deprecated and will soon be removed, following the community vote in ublue-os/main#927.

Users currently building custom bootc images from these deprecated bases need to migrate to actively maintained alternatives. To support this transition, documentation is needed. Even a minimal example would help users add Nvidia support to new base images, so their systems would continue to work as expected.

Refs: ublue-os/main#927 (comment)</issue_description>

<agent_instructions>Implement this using @ublue-os 's current method of enabling nvidia drivers in a bootc image.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@castrojo Ok let's see what we can do with copilot.

Task: Implement the same Nvidia support in the just removed @ublue-os/main repositories in this template. This should allow for anyone to add nvidia support to their custom images.

Look at the techniques implemented by @ublue-os/bazzite @ublue-os/bluefin @ublue-os/aurora and come up with a generalized solution for this repository. It should be obvious for the maintainers to see that the implementation is the same when inspecting the code.

Ignore any nvidia technique or repository that refers to archived repositories, only implement the latest implementation.</comment_new>

Fixes #136

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[tino376dev]

Not sure if this is the right place, but any idea when this might land on the main branch?

[MinimaxHeadroom]

Would it be possible to get additional eyes on this?