enricobuehlerandClaude Fable 5
bfd0de8973
WP2 of the docs-and-onboarding overhaul (punktfunk-planning design/docs-and-onboarding-overhaul.md), stacked on #337 (WP0+WP1). Nav (meta.json) is now Get started / Guides / Switching from Sunshine / Reference / Troubleshooting. Get-started track, rewritten for someone with no Linux expertise — one task per page, happy path, under two minutes each: quickstart (5 steps), install (a pick-your-system hub), ubuntu, debian, fedora, arch, bazzite (+ a firewall step it was missing), a new nixos page (moved out of install), pairing. Every distro page quotes its install snippet through a new <Install platform="…"/> MDX component that reads docs-site/src/data/platforms.json — a byte-identical snapshot of data/platforms.json (the Docker build context is docs-site/ alone, same arrangement as openapi.json) which scripts/ci/check-docs-drift.sh now gates. <Ports/> renders the port table the same way on a new reference page, ports.mdx, so the four distro pages stop restating port lists. platforms.json itself was fixed while wiring it up: the apt snippet lacked the keyring lines, the winget one lacked `winget source add`, the Arch repo-add is now idempotent (grep guard — the documented double-append gotcha disappears at the source), names match the real floors (Ubuntu 26.04+, Windows 11 22H2+), a web-console port entry and the firewall profile names were added, and client platforms (Windows MSIX, macOS, TestFlight, Play, Steam Deck) so the website can render its cards from the same file. Dense material moved down rather than deleted: build-from-source.md (the three distro appendices), the Mint/LMDE/Cinnamon analysis → requirements.md, TOFU/`--open` → security.md, Secure Boot MOK paths and the Arch libavcodec soname refusal → troubleshooting, sysext channels/rollback/rebase → updating.md, the 0.28.1 cert note → windows-host. New page switching-from-sunshine.md: coexistence via the 47990 move (PUNKTFUNK_MGMT_BIND), the Windows display-topology overlap, detect-conflicts exit semantics (1 only for an active host — the troubleshooting page said "non-zero if any"), what maps to what, migration steps. The troubleshooting Sunshine section is tightened and points there. The three facts whose only home was a README now live in troubleshooting — the ffmpeg-libs weak dependency (no NVENC on Fedora), the pacman double-append error, the ds_inhibit SELinux storm with DualSense pads on Bazzite — and packaging/bazzite + packaging/arch READMEs are pointers. Stale claims corrected against the tree: the packaged unit runs the native-only `serve` and GameStream is opt-in on every route (kde, hyprland, security, steamos-host said otherwise); host.env is optional (EnvironmentFile=-); Fedora 43 uses the `bazzite` group; the iOS clipboard bridge exists; PUNKTFUNK_GAMESCOPE_SDR_NITS defaults to 203. Guides trimmed for verbosity (~5% by words — they are fact-dense; every heading, command, number, env var and link target is preserved, verified by token-inventory diffs). Tooling: docs-site README and CONTRIBUTING describe the platforms snapshot; input/uninstall/support-matrix links retargeted. Verified: check-docs-drift.sh and check-docs-links.sh green, docs-site `bun run build` + `bun run lint` green, and the built site served locally to confirm every cross-page anchor the rewrite links to (37) renders, plus the <Install/> blocks and the <Ports/> table. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
4.5 KiB
title, description
| title | description |
|---|---|
| Build from source | Compile the Linux host yourself — on Ubuntu/Debian, Fedora, or with the Arch PKGBUILD — when no package fits your release or you want to track main. |
The package repos are the supported path (Install the Host). Build from source when your release is older than a package supports (Ubuntu before 26.04, Debian 12, a Fedora without a repo group), or to hack on it. A source build gets no packaged units and no clean updates — you wire the service up by hand (Running as a service shows the unit).
Two build features matter on every distro: punktfunk-host/nvenc (direct NVENC on NVIDIA) and
punktfunk-host/vulkan-encode (Vulkan Video on AMD/Intel). They're what the packaged builds use;
without them the host falls back to the slower libav backends. Rust comes from
rustup if you don't have it:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Ubuntu / Debian
The packaged host is built against FFmpeg 8. Ubuntu 26.04's and Debian 13's libavcodec-dev
are new enough; Ubuntu 24.04's is FFmpeg 6.1 — build FFmpeg 8 yourself first there (what
ci/rust-ci-noble.Dockerfile does), or stick with the packaged host.
sudo apt install build-essential pkg-config cmake clang libclang-dev nasm git curl \
pipewire pipewire-pulse wireplumber libpipewire-0.3-dev libspa-0.2-dev \
libwayland-dev wayland-protocols libxkbcommon-dev libopus-dev \
libdrm-dev libgbm-dev libgl-dev libegl-dev libgles-dev mesa-common-dev libva-dev \
ffmpeg libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libavfilter-dev libavdevice-dev \
libnvidia-egl-wayland1 libnvidia-egl-gbm1 libei-dev
git clone https://git.unom.io/unom/punktfunk.git && cd punktfunk
cargo build --release --locked \
--features punktfunk-host/nvenc,punktfunk-host/vulkan-encode \
-p punktfunk-host
Fedora
sudo dnf install gcc gcc-c++ make cmake clang clang-devel nasm git pkgconf-pkg-config \
pipewire-devel wayland-devel wayland-protocols-devel libxkbcommon-devel opus-devel \
libdrm-devel mesa-libgbm-devel mesa-libGL-devel mesa-libEGL-devel mesa-libGLES-devel libva-devel \
ffmpeg-devel libei-devel
git clone https://git.unom.io/unom/punktfunk.git && cd punktfunk
cargo build --release --locked \
--features punktfunk-host/nvenc,punktfunk-host/vulkan-encode \
-p punktfunk-host
ffmpeg-devel must be RPM Fusion's (with NVENC), not ffmpeg-free-devel. mesa-libGL-devel isn't
optional — the zero-copy GPU path links libGL, and without it the build fails at link time with
cannot find -lGL. To build an RPM instead, use the same toolchain CI does:
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.
Arch (PKGBUILD)
The split PKGBUILD in packaging/arch/ produces punktfunk-host and punktfunk-client; set
PF_WITH_WEB=1 to also build punktfunk-web and PF_WITH_SCRIPTING=1 for punktfunk-scripting
(both need bun):
git clone https://git.unom.io/unom/punktfunk.git && cd punktfunk/packaging/arch
PF_SRCDIR="$(git rev-parse --show-toplevel)" makepkg -f --holdver # builds the working tree, no git fetch
sudo pacman -U punktfunk-host-*.pkg.tar.zst
NVENC/EGL come from nvidia-utils; on a GPU-less builder, symlink the CUDA stub into the link path
first (the PKGBUILD header documents this). Packager notes, the Fedora→Arch dependency map and the
sysext mechanism: packaging/arch.
For a SteamOS host don't use the PKGBUILD — the on-device installer builds
ABI-matched to the running OS.
Running what you built
The binary lands at target/release/punktfunk-host. Run it from inside your desktop session — it
auto-detects the compositor:
target/release/punktfunk-host serve # secure native-only host
target/release/punktfunk-host serve --gamestream # + Moonlight compat (trusted LAN only)
To run it as a user service, copy scripts/punktfunk-host.service to
~/.config/systemd/user/ (it already points at %h/punktfunk/target/release/punktfunk-host), then
systemctl --user daemon-reload && systemctl --user enable --now punktfunk-host. The other
workspace members (punktfunk-web, punktfunk-scripting, the client) build the same way — the
root README covers the dev loop.