punktfunk/docs-site/content/docs/fedora-kde.md

title, description

title	description
Fedora — KDE Plasma	Reproducible punktfunk host setup on Fedora KDE (KWin) via the RPM.

Set up a punktfunk host on Fedora KDE (the KDE Plasma spin). The host runs as an RPM-managed systemd service and uses KWin to create per-client virtual displays, captured zero-copy (dmabuf → CUDA → NVENC) on NVIDIA.

Validated live on Fedora 44 KDE Plasma with an RTX 4090: KWin virtual output + full zero-copy capture. Everything below is the reproducible flow — paste it on a fresh box.

The setup has three parts: NVIDIA driver → host RPM → KWin streaming session.

1. NVIDIA driver (RPM Fusion akmod)

Enable RPM Fusion (free + nonfree), then install the akmod driver + CUDA. RPM Fusion's nonfree NVIDIA repo is sometimes pre-enabled on the KDE spin; the full free/nonfree repos below are still needed (they carry the NVENC ffmpeg in the next step).

sudo dnf install \
  https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm \
  https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
sudo dnf install akmod-nvidia xorg-x11-drv-nvidia-cuda

NVENC ffmpeg. Fedora ships ffmpeg-free, which is built without NVENC — the host can't encode with it. Swap to RPM Fusion's ffmpeg:

sudo dnf install --allowerasing ffmpeg ffmpeg-libs
ffmpeg -hide_banner -encoders | grep nvenc   # expect hevc_nvenc / av1_nvenc / h264_nvenc

Secure Boot. If mokutil --sb-state says enabled, the akmod module is signed with a locally-generated key that must be enrolled once:

sudo akmods --force                                              # build + sign the module
sudo mokutil --import /etc/pki/akmods/certs/public_key.der       # set a one-time password
sudo reboot

On the next boot a blue MOK Manager screen appears on the machine's console (not over SSH): Enroll MOK → Continue → Yes → (the password) → Reboot. Then verify:

nvidia-smi                              # driver loads
ffmpeg -hide_banner -encoders | grep nvenc

(Or disable Secure Boot in firmware to skip the MOK step — fine for a dedicated test box.)

2. Install the host (RPM)

The host is published to the self-hosted Gitea RPM registry, in a per-Fedora-release group (an RPM is soname-coupled to its base, so Fedora 44 has its own fedora-44 group). Add the repo and install:

sudo tee /etc/yum.repos.d/punktfunk.repo >/dev/null <<'REPO'
[punktfunk]
name=punktfunk
baseurl=https://git.unom.io/api/packages/unom/rpm/fedora-44
enabled=1
# Packages are GPG-signed (gpgcheck=1) AND the repo metadata is Gitea-signed (repo_gpgcheck=1).
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://git.unom.io/api/packages/unom/rpm/repository.key
       https://git.unom.io/api/packages/unom/generic/punktfunk-keys/1/RPM-GPG-KEY-punktfunk
REPO

sudo dnf install punktfunk
sudo usermod -aG input "$USER"     # /dev/uinput access for virtual gamepads (re-login to apply)

Updates later are just sudo dnf upgrade punktfunk. The package ships the systemd user units, the udev rule, the UDP socket-buffer sysctl tuning, and example configs.

No matching fedora-NN group for your release yet? Build one with the same toolchain CI uses — docker build --build-arg FEDORA_VERSION=NN -f ci/fedora-rpm.Dockerfile -t pf-rpm ci then run packaging/rpm/build-rpm.sh inside it — or build from source (appendix below).

3. KWin streaming session

KWin's virtual-output capture uses its privileged zkde_screencast protocol, which an interactive Plasma session will not hand to an external client. So the host streams from a dedicated headless KWin session (kwin --virtual launched with KWIN_WAYLAND_NO_PERMISSION_CHECKS=1) — shipped as punktfunk-kde-session.service. This also makes the box a self-contained appliance: it streams at boot with no graphical login.

# KWin appliance config (ships with the package):
mkdir -p ~/.config/punktfunk
cp /usr/share/punktfunk/host.env.kde ~/.config/punktfunk/host.env

# Start the headless KWin session + the host, and start user units at boot without a login:
systemctl --user daemon-reload
systemctl --user enable --now punktfunk-kde-session punktfunk-host
sudo loginctl enable-linger "$USER"

Check it came up:

systemctl --user status punktfunk-host          # active
journalctl --user -u punktfunk-host -f          # watch a client connect

The host now listens on 9777 (native punktfunk/1) + the GameStream ports, and advertises over mDNS. It requires PIN pairing by default (secure on a LAN); pair once from your client.

Web console

The console (status, paired devices, arm pairing) ships as punktfunk-web — enable it, then open http://<host-ip>:3000:

systemctl --user enable --now punktfunk-web

Console login password

The console is password-protected. On first start punktfunk-web-init generates a random login password and saves it to ~/.config/punktfunk/web-password (as PUNKTFUNK_UI_PASSWORD=…). Read it back at any time — from the init service's journal, or straight from the file:

journalctl --user -u punktfunk-web-init | sed -n 's/.*password generated: //p'
sed -n 's/^PUNKTFUNK_UI_PASSWORD=//p' ~/.config/punktfunk/web-password

To set your own password, edit that file (PUNKTFUNK_UI_PASSWORD=<your-password>) and restart the console: systemctl --user restart punktfunk-web. Forgot it? This is the recovery path linked from the console login screen — see Forgot your Password?.

4. Connect a client

From any client — punktfunk-client --discover finds the host on the LAN. On first connect, complete the PIN pairing — arm it from the host's web console / mgmt API, which makes the host display a 4-digit PIN to type into the client. (Pairing is required by default; pass serve --open only if you deliberately want to disable the requirement.) See Clients and Running as a Service.

Appendix — build from source

If there's no RPM for your Fedora release and you don't want to build one, compile the host directly (no clean updates / no packaged units — you wire those up by hand):

sudo dnf install gcc gcc-c++ make cmake clang clang-devel nasm git \
  pipewire-devel wayland-devel wayland-protocols-devel libxkbcommon-devel opus-devel \
  libdrm-devel mesa-libgbm-devel mesa-libEGL-devel mesa-libGLES-devel libva-devel \
  ffmpeg-devel libei-devel
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
git clone https://git.unom.io/unom/punktfunk.git && cd punktfunk
cargo build --release -p punktfunk-host

Then write ~/.config/punktfunk/host.env (as in /usr/share/punktfunk/host.env.kde, but the host binary is target/release/punktfunk-host) and run it inside the KWin session from step 3.