blueHTPC

Custom Home Theather PC operating system with Plasma Bigscreen and pre-installed apps, based on bootc/universal blue(the project is NOT affiliated with universal blue, it's just based on their OS)

Features

• Kinoite base - Fedora Kinoite with KDE Plasma
• Plasma Bigscreen - TV-friendly 10-foot UI as the default session
• Auto-login - Automatically logs into Plasma Bigscreen on first boot after install
• Pre-installed packages - Firefox, plasma-bigscreen, Flatpak support
• Pre-installed Flatpaks - VacuumTube, Plex HTPC, Stremio, Kodi, Flathub remote configured
• Bigscreen favorites - All apps pre-pinned to the Plasma Bigscreen home screen
• uBlock Origin - Auto-installed in Firefox via enterprise policy
• Auto-updates - Daily bootc upgrade + flatpak update via systemd timer
• Anaconda ISO - Full KDE installer with interactive setup (user creation, disk partitioning, etc.)
• Laptops
  • Prevent sleep, suspend, and hibernation(lid can be closed while HDMI remains active)
  • Prevent audio from cutting out after idle

Quick Start

Install from ISO

1. Download the latest ISO (GitHub account needed) from the Actions page: click the latest run(first on the list) → Artifacts or build it (see Dev section).
2. Extract the artifact to get install.iso and use it in Fedora Media Writer or a similar program to burn the ISO into a flash drive
3. Boot the ISO and go through the Anaconda installer
4. On first boot, you'll be auto-logged into Plasma Bigscreen

Switch from an existing bootc system

sudo bootc switch ghcr.io/douglascdev/bluehtpc:latest
sudo reboot

Dev

Prerequisites

• podman and just installed
• sudo access

Clone

git clone https://github.com/douglascdev/blueHTPC
cd blueHTPC

Build the container image locally

just build

Or build as root (to rebase directly):

sudo just build

Build disk images (ISO / QCOW2)

# Build ISO (builds container image + ISO in one step)
sudo just rebuild-iso

# Build QCOW2
sudo just rebuild-qcow2

Run the ISO in a VM

# Build the ISO first
sudo just rebuild-iso

Open GNOME Boxes, click + → Import Image, and select output/bootiso/install.iso.

The ISO runs the Anaconda installer. Once installed, the VM will boot into blueHTPC with Plasma Bigscreen on each subsequent start.

Maintainers: Testing changes without reinstalling

After installing from the ISO once, you can iterate on changes without rebuilding the ISO:

# 1. Build the updated image locally
sudo just build

# 2. Push to a test tag (keeps :latest clean for production)
# GH_TOKEN -> a github PAT with write:packages scope
sudo podman login ghcr.io -u login -p "$GH_TOKEN"
sudo podman push localhost/bluehtpc:latest ghcr.io/douglascdev/bluehtpc:testing

# 3. In the VM, switch to the test tag and reboot
sudo bootc switch ghcr.io/douglascdev/bluehtpc:testing
sudo reboot

Production systems pinned to :latest are unaffected. Once you're satisfied, push to :latest for production rollout.

Customizing

Adding packages

Edit build_files/build.sh and add packages to the dnf5 install line for RPMs, or a new flatpak install line for Flatpaks:

dnf5 install -y firefox flatpak plasma-bigscreen my-new-package
flatpak install -y com.example.MyApp

Adding apps to Bigscreen favorites

Edit system_files/etc/skel/.config/bigscreen-favs. Each entry has an index ([Favs][N]) followed by fields describing the app launcher. To add a new app, append a new block with the next index. The desktopPath and entryPath should match the app's .desktop file:

[Favs][5]
categories=AudioVideo
comment=My App description
desktopPath=/var/lib/flatpak/exports/share/applications/com.example.MyApp.desktop
entryPath=/usr/bin/flatpak run --branch=stable --arch=x86_64 --command=myapp com.example.MyApp
icon=com.example.MyApp
name=My App
startupNotify=false
storageId=com.example.MyApp.desktop

For system (non-Flatpak) apps, desktopPath goes under /usr/share/applications/ and entryPath is the command directly.

Adding system files

Drop files into system_files/ mirroring the root filesystem layout. They are copied to / during the build. For example:

• system_files/etc/firefox/policies/policies.json → /etc/firefox/policies/policies.json
• system_files/usr/lib/systemd/system/my-service.service → /usr/lib/systemd/system/my-service.service

Then enable any new systemd units in build_files/build.sh:

systemctl enable my-service.service

Modifying the ISO installer

Edit disk_config/iso-kde.toml to change Anaconda kickstart behavior or installer modules. The bootc switch line in the %post section determines which image gets installed - update it if you push to a different registry or image name.

Building via GitHub Actions

Push to main - the build.yml workflow automatically builds and pushes to GHCR. Trigger the build-disk.yml workflow manually from the Actions tab to produce ISOs and QCOW2 images as downloadable artifacts.