enricobuehler
861da54066
Port 3000 collides with half the dev-server ecosystem; 47992 sits next to the mgmt API (47990) in the punktfunk port family. Updates the run scripts, systemd/scheduled-task units, Dockerfile, Windows firewall rule + installer, packaging, and every doc that referenced :3000. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
4.9 KiB
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>:47992
journalctl --user -u punktfunk-web-init | sed -n 's/.*password generated: //p'
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?.
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 --gamestream
(The native plane is always on; --gamestream adds the Moonlight-compat surface this guide's
GameStream ports refer to — trusted LAN only. Drop it for a secure native-only host.)