punktfunk/docs-site/content/docs/ubuntu-kde.md at b8c9f88cfda579a0aeb30d5259caf5767e708d78

Files

T

enricobuehler 9e015304ee docs(dist): end-user install front door + serve/pairing/firewall accuracy fixes

Make the host docs match the real distribution path and the actual CLI. Reviewed by a
multi-agent pass (6 editors against one verified fact sheet + an accuracy reviewer); its
findings (a wrong client-Recommends claim, a native-concurrency overstatement) folded in.

- Install front door: new README "Install (host)" method-picker + docs-site/install.md
  (+ nav), routing each distro to its package registry; source build demoted to a fallback.
- Registry-first install: ubuntu-gnome/ubuntu-kde now lead with the apt registry (not a
  cargo build); bazzite leads with the Gitea RPM registry (was COPR/source). Source builds
  moved to an appendix.
- CLI accuracy: serve --native arms pairing from the web console (NOT --allow-pairing, which
  with --require-pairing/--max-concurrent is m3-host-only); --open disables mandatory pairing.
  host-cli/configuration/pairing/quickstart/troubleshooting corrected; mgmt API documented as
  always HTTPS+token. Native host serves one session at a time (extras queue) — not multi.
- Firewall: real ports documented (native UDP 9777 + the ephemeral data port caveat +
  GameStream ports) for Debian + Arch (ufw + nftables), not just Bazzite.
- Sync/accuracy: punktfunk-client (GTK4) presented as a shipping client (not "roadmap"),
  punktfunk-client-rs as the headless tool; host Recommends punktfunk-web only (not the
  client); COPR chroots f43/44; bootc header says Gitea registry not COPR.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-15 10:43:12 +00:00

4.0 KiB

Raw Blame History

title, description

title	description
Ubuntu — KDE Plasma	Set up a punktfunk host on Ubuntu with KDE Plasma (KWin).

Set up a punktfunk host on Ubuntu running KDE Plasma. The host uses KDE's KWin compositor to create a per-client virtual display. Needs KWin 6.5.6 or newer.

New to this? Skim Requirements first.

1. NVIDIA driver

Identical to the GNOME guide — follow step 1 of Ubuntu — GNOME: install the NVIDIA driver and the libnvidia-gl-<version> userspace, enable nvidia-drm modeset=1, reboot, and verify with nvidia-smi.

2. Install the host (apt)

The host is published as a .deb to the public Gitea apt registry — install and update with plain apt. Trust the repo's signing key, add the repo, and install:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://git.unom.io/api/packages/unom/debian/repository.key \
  | sudo tee /etc/apt/keyrings/punktfunk.asc >/dev/null

echo "deb [signed-by=/etc/apt/keyrings/punktfunk.asc] https://git.unom.io/api/packages/unom/debian stable main" \
  | sudo tee /etc/apt/sources.list.d/punktfunk.list

sudo apt update
sudo apt install punktfunk-host

This also pulls the web console (punktfunk-web) via Recommends (the pairing/status UI). The desktop client — punktfunk-client, for the machine you stream to — is a separate package, not needed on a host. The NVIDIA driver stays out of band (step 1). Updates later are just sudo apt update && sudo apt upgrade.

3. Configure

The package ships the systemd user unit, the udev rule, and the sysctl tuning. As the desktop user, grant gamepad access and write the KDE config:

sudo usermod -aG input "$USER"     # /dev/uinput for virtual gamepads (re-login to apply)
mkdir -p ~/.config/punktfunk
cat > ~/.config/punktfunk/host.env <<'ENV'
WAYLAND_DISPLAY=wayland-0
XDG_CURRENT_DESKTOP=KDE
PUNKTFUNK_COMPOSITOR=kwin
PUNKTFUNK_VIDEO_SOURCE=virtual
PUNKTFUNK_ZEROCOPY=1
PUNKTFUNK_INPUT_BACKEND=libei
ENV

Make sure you're on a KDE Wayland session (not X11) — the picker on the login screen. The virtual-display path is Wayland-only. See the Configuration reference for every option.

4. Run

Start the host as a user service from inside your Plasma session:

systemctl --user enable --now punktfunk-host
journalctl --user -u punktfunk-host -f      # watch it come up + print its fingerprint

The host listens on UDP 9777 (native punktfunk/1) plus the GameStream ports and advertises over mDNS. It requires PIN pairing by default — arm pairing from the web console and pair once from your client.

Web console

systemctl --user enable --now punktfunk-web
# read the auto-generated login password, then open http://<host-ip>:3000
journalctl --user -u punktfunk-web-init | sed -n 's/.*password generated: //p'

To run it at boot — including fully headless, with KWin brought up automatically and no login — see Running as a Service; the headless appliance is built around KDE.

Troubleshooting

KWin too old: virtual outputs need KWin ≥ 6.5.6. Check with kwin_wayland --version.
No picture / capture fails: confirm you're on a Wayland session and the NVIDIA GL userspace is installed (libnvidia-gl-<version>). More in Troubleshooting.

Appendix — build from source

If the apt registry has no build for your release, compile the host yourself (no clean updates / no packaged units). Install the build toolchain and runtime libraries — the same apt line as the GNOME build-from-source appendix — then:

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

Write ~/.config/punktfunk/host.env as in step 3, then run it inside your Plasma session:

cargo run --release -p punktfunk-host -- serve --native

4.0 KiB Raw Blame History