Bazzite Administrator & Developer Guide

1. Architecture Overview

Bazzite is a gaming-focused Linux distribution built as an OCI container image on top of Fedora Atomic Desktop (Silverblue/Kinoite) through the Universal Blue (ublue-os) framework. The system is immutable: the root filesystem is delivered as a container image, updates are atomic image replacements, and user customization happens through overlay mechanisms (/etc, Flatpak, Distrobox, Homebrew).

The build pipeline produces multiple image variants from a single Containerfile using multi-stage targets. Each variant combines a Fedora Atomic base with Bazzite's custom kernel, patched system packages (via RPM spec files), desktop environment presets, hardware-specific configurations, and a library of ujust administrative recipes.

Architecture Diagram

┌─────────────────────────────────────────────────────────┐
│                    Bazzite Image                        │
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐ │
│  │ Fedora Atomic │  │ Bazzite      │  │ Hardware      │ │
│  │ Base Layer    │  │ Overlay      │  │ Profiles      │ │
│  │ (Silverblue   │  │ (packages,   │  │ (WirePlumber, │ │
│  │  or Kinoite)  │  │  configs,    │  │  PipeWire,    │ │
│  │              │  │  services)   │  │  udev, EDID)  │ │
│  └──────┬───────┘  └──────┬───────┘  └──────┬────────┘ │
│         └─────────────┬───┘─────────────────┘           │
│                       ▼                                  │
│  ┌─────────────────────────────────────────────────────┐│
│  │              Containerfile (multi-target)            ││
│  │  Targets: bazzite | bazzite-deck | bazzite-nvidia   ││
│  └─────────────────────────────────────────────────────┘│
│                       ▼                                  │
│  ┌──────────┐  ┌──────────┐  ┌────────────────────────┐│
│  │ just     │  │ systemd  │  │ Desktop Environment    ││
│  │ recipes  │  │ services │  │ GNOME / KDE presets     ││
│  │ (ujust)  │  │ & timers │  │ Extensions, themes,    ││
│  │          │  │          │  │ dconf/gsettings         ││
│  └──────────┘  └──────────┘  └────────────────────────┘│
└─────────────────────────────────────────────────────────┘
         │                    │
         ▼                    ▼
┌─────────────┐    ┌─────────────────┐
│ Flatpak     │    │ Distrobox       │
│ (user apps) │    │ (mutable Linux) │
└─────────────┘    └─────────────────┘

Component Inventory

Technology Stack

Note

Bazzite does not run its own API server or web service — it is purely an OS image. The "architecture" is the image build pipeline and the runtime configuration it produces.

2. System Requirements

Build Requirements

Runtime Requirements

3. Configuration Reference

System Files Hierarchy

Bazzite overlays configuration files onto the Fedora base during image build. Files are organized by variant:

system_files/
├── desktop/                    # All desktop variants
│   ├── shared/                 # Common to GNOME + KDE desktop
│   │   ├── etc/                # /etc overrides
│   │   └── usr/                # /usr additions
│   ├── silverblue/             # GNOME-specific
│   └── kinoite/                # KDE-specific
├── deck/                       # Handheld/HTPC (Game Mode) variants
│   ├── shared/                 # Common to all deck
│   ├── silverblue/             # Deck + GNOME
│   └── kinoite/                # Deck + KDE
├── nvidia/                     # NVIDIA GPU variants
│   ├── shared/                 # Common NVIDIA
│   ├── silverblue/             # NVIDIA + GNOME
│   └── kinoite/                # NVIDIA + KDE
└── overrides/                  # Applied to ALL variants (branding, CLI tools)

Key Configuration Files

Environment Variables

Sysctl Parameters

Kernel Module Configuration

Security Limits

Important

All files under /usr are immutable at runtime. To override, create corresponding files under /etc or use rpm-ostree kargs for kernel parameters. Changes to /usr require rebuilding the image.

Dracut Configuration

4. Deployment & Scaling

Image Build Process

The Justfile provides the developer interface for building images and ISOs:

Build an image:

just build <target> <desktop>

The build script (just_scripts/build-image.sh) runs:

$container_mgr build -f Containerfile \
    --build-arg="IMAGE_NAME=${tag}" \
    --build-arg="BASE_IMAGE_NAME=${base_image}" \
    --build-arg="KERNEL_FLAVOR=bazzite" \
    --build-arg="SOURCE_IMAGE=${base_image}-${flavor}" \
    --build-arg="FEDORA_VERSION=${latest}" \
    --target="${target}" \
    --tag localhost/"${tag}:${latest}-${git_branch}" \
    "${project_root}"

Note

The build automatically selects podman, docker, or podman-remote via just_scripts/container_mgr.sh. Set CONTAINER_MGR environment variable to force a specific runtime.

Build an ISO:

just build-iso <target> <desktop>

ISO builds require a rootful container runtime (cannot run inside rootless podman). The process:

1. Builds the container image if not already present
2. Generates Flatpak dependency list using a temporary container
3. Runs ghcr.io/jasonn3/build-container-installer to produce the ISO

Warning

ISO builds cannot run inside rootless containers. The script checks for /run/.containerenv and the root status of the container manager before proceeding.

Build arguments:

ISO Configuration

The ISO is configured via installer/iso.yaml:

label: "Bazzite-Live"
grub2:
  timeout: 3
  entries:
    - name: "Launch Bazzite Installer"
      linux: "/images/pxeboot/vmlinuz quiet rhgb root=live:CDLABEL=Bazzite-Live enforcing=0 rd.live.image"
      initrd: "/images/pxeboot/initrd.img"
    - name: "Launch Bazzite Installer (Basic Graphics Mode)"
      linux: "/images/pxeboot/vmlinuz quiet rhgb root=live:CDLABEL=Bazzite-Live enforcing=0 rd.live.image nomodeset"
      initrd: "/images/pxeboot/initrd.img"

Container Registry

Built images are published to GitHub Container Registry:

ghcr.io/ublue-os/bazzite-gnome:42
ghcr.io/ublue-os/bazzite-kde:42
ghcr.io/ublue-os/bazzite-deck-gnome:42
ghcr.io/ublue-os/bazzite-gnome-nvidia:42
...

Images are signed with Cosign. The public key is at /cosign.pub in the repository root.

Test an Image Locally

just run-image <target> <desktop>

This starts the built image in an interactive container session.

Test an ISO in QEMU:

just run-iso <target> <desktop>

Runs the ISO in qemux/qemu-docker with KVM, accessible at http://127.0.0.1:8006. Configuration: 2 CPU cores, 4 GB RAM, 64 GB virtual disk, UEFI boot.

Cleanup

just clean-images    # Remove built container images
just clean-dir       # Remove built ISOs from output/

5. Operations

Systemd Services — Desktop Variants

Tip

All services are enabled/disabled at image build time. Runtime enable/disable via systemctl persists across updates since /etc/systemd is in the mutable layer.

Systemd Services — Deck Variants

HHD (Handheld Daemon) Integration

Deck variants include systemd drop-in overrides for HHD services:

Polkit Rules

udev Rules

Note

The 99-powertargets.rules file activates ac.target or battery.target based on power state, enabling conditional service activation.

Announcements System

Bazzite includes a built-in announcement system for notifying users of breaking changes:

File format: JSON files at /usr/share/ublue-os/announcements/ with .msg.json suffix.

{
  "title": "Breaking change",
  "body": "Description of the change",
  "seeMoreUrl": "https://example.com/details",
  "if": "systemd-analyze compare-versions 43 \\< $(rpm-ostree status -v --json | jq -r '.deployments[]|select(.booted==true)|.version')"
}

The prepare_msg.sh script creates announcement JSON interactively.

Tip

Use the if field to schedule announcements ahead of time — they trigger only when the system updates to a matching version.

Update Flow

1. uupd.timer triggers periodic update checks
2. bootc switch --mutate-in-place pulls the new image
3. Image is staged as a new deployment
4. On reboot, the new deployment becomes active
5. Previous deployment remains available for rollback

Greenboot Health Checks

Bazzite configures Greenboot for boot health verification:

/etc/greenboot/greenboot.conf

If health checks fail after an update, Greenboot automatically rolls back to the previous deployment.

6. Performance

Tuned Profiles

Bazzite ships custom tuned profiles with sched_ext scheduler integration:

Profile scripts are at /usr/lib/tuned/profiles/*/script.sh. Each uses scxctl switch -m <mode> to set the sched_ext scheduler when scx_loader.service is enabled.

Kernel Parameters

Desktop (/usr/lib/sysctl.d/):

Deck (/usr/lib/sysctl.d/):

Logind Configuration (Deck)

/etc/systemd/logind.conf.d/deck.conf     — Session handling for Game Mode
/usr/lib/systemd/logind.conf.d/killuserprocesses.conf — Kill user processes on logout

Journal Configuration (Deck)

/usr/lib/systemd/journald.conf.d/00-journal-persistent.conf — Persistent journal storage
/usr/lib/systemd/journald.conf.d/00-journal-size.conf       — Journal size limits

7. Security

Image Signing

All official Bazzite images are signed with Cosign (Sigstore). The public key is distributed at:

• Repository: /cosign.pub
• Image: /usr/share/ublue-os/sb_pubkey.der (Secure Boot variant)

The verification script (/etc/profile.d/verify_motd.sh) checks at login whether the running deployment is signed:

CURRENT_REF=$(rpm-ostree status --json | jq -r '.deployments[0]["container-image-reference"] // empty')
if [[ "$CURRENT_REF" == *"ostree-unverified-registry"* ]] && [[ "$CURRENT_REF" == *"ghcr.io/ublue-os/"* ]]; then
    # Display security warning
fi

Warning

Running an unverified image disables automatic updates and container signature verification. Users see a red terminal warning on every login until resolved with ujust verify-image.

Secure Boot

Bazzite supports UEFI Secure Boot via Machine Owner Key (MOK) enrollment:

• Enrollment password: universalblue (hardcoded in installer)
• Key URL: https://github.com/ublue-os/akmods/raw/main/certs/public_key.der
• Skip condition: Steam Deck (Jupiter/Galileo) hardware skips enrollment automatically
• Key location in image: /usr/share/ublue-os/sb_pubkey.der

The installer generates a QR code linking to https://docs.bazzite.gg/sb for documentation.

Installer Security

The ISO installer includes security checks:

1. BitLocker detection: Scans lsblk for BitLocker partitions and warns users with a dialog (including QR code to wikihow.com BitLocker disable guide)
2. Signed image switch: After installation, bootc switch --enforce-container-sigpolicy ensures the installed system uses signed images
3. EFI partition cleanup: Removes previous Fedora EFI entries to prevent boot confusion

SELinux

NVIDIA variants include a custom SELinux policy module:

/usr/share/selinux/packages/nvidia-container.pp

Caution

The live ISO boots with enforcing=0 (SELinux permissive) to avoid installer conflicts. The installed system runs in enforcing mode.

Polkit Security Boundaries

Polkit rules define privilege escalation boundaries. Key policies:

8. Developer Internals

Repository Structure

.
├── Containerfile                 # Multi-stage OCI image build
├── Justfile                      # Developer task runner
├── LICENSE                       # License
├── cosign.pub                    # Image signing public key
├── secure_boot.der               # Secure Boot certificate
├── artifacthub-repo.yml          # ArtifactHub registry metadata
├── build_files/                  # Build-time scripts
│   ├── build-gnome-extensions    # Compile GNOME Shell extensions
│   ├── build-initramfs           # Regenerate initramfs
│   ├── cleanup                   # Post-build cleanup
│   ├── dnf5-search / dnf5-setopt # DNF5 helpers
│   ├── finalize                  # Final image preparation
│   ├── ghcurl                    # GitHub release downloader
│   ├── image-info                # Write image metadata JSON
│   ├── install-kernel             # Custom kernel installation
│   └── install-nvidia            # NVIDIA driver installation
├── installer/                    # ISO installer
│   ├── build.sh                  # ISO rootfs preparation
│   ├── iso.yaml                  # GRUB/ISO configuration
│   ├── Containerfile             # Installer container build
│   ├── titanoboa_hook_*.sh       # Pre/post rootfs hooks
│   ├── branding/                 # Anaconda artwork
│   ├── gnome_flatpaks/flatpaks   # Default GNOME Flatpaks
│   ├── kde_flatpaks/flatpaks     # Default KDE Flatpaks
│   └── lorax_templates/          # Lorax customization
├── just_scripts/                 # Shell scripts for Justfile
├── spec_files/                   # Patched RPM specs (30+ packages)
├── system_files/                 # Overlay files for image variants
├── firmware/                     # Custom firmware blobs
├── tests/                        # Container image tests
│   └── dgoss/                    # dgoss test runner
└── press_kit/                    # Brand assets

Forked Packages (spec_files/)

Bazzite maintains custom RPM spec files with patches for these upstream packages:

Hardware Profiles

WirePlumber Profiles

Device-specific audio routing at /usr/share/wireplumber/hardware-profiles/:

Global WirePlumber config at /usr/share/wireplumber/wireplumber.conf.d/:

PipeWire Filter Chains

Device-specific DSP at /usr/share/pipewire/hardware-profiles/:

Display Profiles

Gamescope display configuration at /usr/share/gamescope/scripts/00-gamescope/displays/:

The Lua script defines colorimetry, HDR capabilities, and dynamic mode generation for per-device display support.

Color Profiles (ICC)

EDID Firmware

Custom EDID blobs at /usr/lib/firmware/edid/:

ALSA UCM Profiles

/usr/share/alsa/ucm2/USB-Audio/Sony/DualSense-PS5.conf

Custom Use Case Manager profile for PS5 DualSense controller audio.

GNOME Shell Extensions

The GNOME (Silverblue) variant bundles these extensions:

KDE Plasma Customization

Default taskbar pins (set via bazzite-pins.js Plasma update script):

widget.writeConfig("launchers", [
    "preferred://browser",
    "applications:steam.desktop",
    "applications:net.lutris.Lutris.desktop",
    "applications:org.kde.konsole.desktop",
    "applications:io.github.kolunmi.Bazaar.desktop",
    "applications:io.github.ublue_os.yafti_gtk.desktop",
    "preferred://filemanager"
]);

Themes: Vapor (stock SteamOS theme, com.valve.vapor.desktop) and VGUI2 (green theme, com.valve.vgui.desktop) are available.

Templates: KDE file templates for MangoHud, DXVK, and vkBasalt configuration files.

Add-to-Steam Nautilus Extension

A Python Nautilus extension (steamos-add-to-steam.py) provides "Add to Steam" in the GNOME file manager:

class AddToSteamExtension(GObject.GObject, Nautilus.MenuProvider):

Supported MIME types:

• application/x-desktop
• application/x-executable
• application/vnd.appimage
• application/x-shellscript
• application/x-ms-dos-executable

The extension calls /usr/bin/steamos-add-to-steam with the selected file path.

Installer Internals

The installer pipeline (installer/titanoboa_hook_postrootfs.sh) performs:

1. Remove all RPM versionlocks
2. Install Anaconda, Firefox, block device libraries
3. Install QR code generator (qrencode) and dialog tool (yad)
4. Install Conky for live desktop hardware info display
5. Detect image variant and apply branding
6. Fetch and enroll Secure Boot key
7. Generate Kickstart file with:
   • BitLocker detection and warning dialog
   • EFI partition cleanup
   • Boot partition relabeling (bazzite_xboot)
   • Error dialog on installation failure
   • Deck variant: default user creation (bazzite:bazzite)
   • Post-install: signed image switch, Flatpak install, SELinux relabel
8. Disable non-essential services for live session
9. Apply NVIDIA workarounds for live session (GSK_RENDERER, nouveau reinstall)
10. Desktop-environment-specific setup (GNOME keyboard, KDE pins, wallpapers)

The pre-initramfs hook (installer/titanoboa_hook_preinitramfs.sh) swaps the custom kernel for a vanilla signed kernel to support Secure Boot on the live ISO.

Testing Framework

Tests use dgoss (Docker/container variant of Goss):

tests/dgoss/dgoss-tests.sh <tests-dir> <image-ref>

The runner:

1. Sets CONTAINER_RUNTIME=podman
2. Discovers test.sh scripts in test directories
3. Runs each test against the specified image

Current test suite: tests/dgoss/tests.d/00-smoke/ — basic smoke test that validates the container starts successfully.

dgoss run "${image}"

Hardware Support Detection Scripts

Utility scripts at /usr/libexec/hwsupport/:

ArtifactHub Registration

The repository is registered on ArtifactHub for OCI image discovery:

repositoryID: 6f68e5bb-ffaf-4a70-9c1b-b154b772044e
owners:
  - name: Jorge Castro
    email: [email removed]

Code Patterns

• Shell scripts dominate: The codebase is primarily bash scripts, systemd units, and configuration files. Only one Python file exists (steamos-add-to-steam.py).
• Variant selection via path convention: system_files/{variant}/{de_base}/ maps directly to the filesystem overlay applied during image build.
• Conditional builds via Containerfile targets: --target=bazzite-deck vs --target=bazzite-nvidia selects the build variant.
• Just as user-facing CLI: End users run ujust <recipe> rather than raw system commands. The just recipe files in /usr/share/ublue-os/just/ are numbered for load order (10, 80-92, 95).

Known Issues and Workarounds

Contributing

1. Fork the repository
2. Create a branch for your change
3. Make changes following the existing conventions:
   • Shell scripts: set -euo pipefail, shellcheck compatible
   • System files: mirror the OS filesystem path structure under system_files/
   • Spec files: maintain upstream compatibility with Fedora specs
4. Test with just build <target> <desktop> and just run-image <target> <desktop>
5. Submit a pull request

Note

The dgoss test suite runs during CI. Ensure tests/dgoss/tests.d/00-smoke/ passes for your variant before submitting.

9. Integration Points

Universal Blue Ecosystem

Bazzite builds on the Universal Blue framework:

• Base images: ghcr.io/ublue-os/silverblue-main, ghcr.io/ublue-os/kinoite-main
• NVIDIA images: ghcr.io/ublue-os/silverblue-nvidia, ghcr.io/ublue-os/kinoite-nvidia
• Shared infrastructure: ublue-os akmods (kernel modules), bling (CLI tools), yafti (first-boot wizard)
• ISO builder: ghcr.io/jasonn3/build-container-installer

Bazaar App Store

Bazzite integrates the Bazaar application store:

• Configuration at /usr/share/ublue-os/bazaar/
• Content categories: main.yaml, content.yaml
• Blocklist: blocklist.yaml
• Custom hooks: hooks.py
• Category icons: gaming, music, office, streaming, utilities

Topgrade Integration

System updates are coordinated through Topgrade:

• Config: /etc/ublue-os/topgrade.toml and /usr/share/ublue-os/topgrade.toml
• Custom update scripts at /usr/libexec/topgrade/:
  • mozilla-gnome-theme-update — Update Firefox GNOME theme
  • third-party-css-loader-update — Update CSS Loader themes

NetworkManager with iwd Backend

Bazzite configures NetworkManager to use iwd as the WiFi backend:

/usr/lib/NetworkManager/conf.d/50-iwd.conf       — Set wifi.backend=iwd
/usr/lib/NetworkManager/conf.d/51-iwd-config.conf — iwd-specific settings

The custom iwd package includes a patch removing 802.1X restrictions for unknown networks.

NVIDIA Container Toolkit (NVIDIA Variants)

NVIDIA variants include container GPU support:

/usr/lib/systemd/system/ublue-nvctk-cdi.service  — NVIDIA Container Toolkit CDI generation
/usr/libexec/nvidia-legacy-hardware               — Legacy NVIDIA hardware detection

Distrobox Configuration

NVIDIA variant has a separate Distrobox configuration:

/etc/distrobox/distrobox.ini        — Standard variant
/nvidia/shared/etc/distrobox/distrobox.ini — NVIDIA variant (includes GPU passthrough)