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>
3.8 KiB
title, description
| title | description |
|---|---|
| Quick Start | From nothing to streaming in five steps — install a host, open its console, pair a client, play. |
Five steps, each linking to the detail only if you need it. Punktfunk is built for a trusted home network — keep the host on your LAN or a VPN, never open it to the internet (why).
1. Install the host
On the PC you want to stream from, follow the one-page guide for its system — each one is the install command, the group to join, and nothing else:
| Linux | Windows |
|---|---|
| Ubuntu · Debian · Fedora · Arch / CachyOS · Bazzite · SteamOS · NixOS | Windows 11 |
Not sure your machine qualifies? Requirements is the checklist.
2. Start it
-
Windows and SteamOS: nothing to do — the installer started the host and the web console, and they come back on every boot.
-
Linux packages: from a terminal inside your desktop session, start the host and the console once; they restart at every login from then on:
systemctl --user enable --now punktfunk-host punktfunk-webOn Arch install
punktfunk-webfirst (your install page says how). Running a firewall? Your install page has the one line that opens it.
The host announces itself on your network, so clients find it by name. It works out which desktop you run by itself — there is nothing to configure for a first stream.
3. Open the web console
The console is where you admit new devices. Open https://<host-ip>:47992 in a browser (the
certificate is the host's own, so your browser warns once — continue) and log in:
- Linux: the password was generated on first start — print it with
sed -n 's/^PUNKTFUNK_UI_PASSWORD=//p' ~/.config/punktfunk/web-password(SteamOS: the install script printed it; it's in~/.config/punktfunk/web.env). - Windows: the installer showed it on its last page.
Lost it? Forgot your password. Everything else about the console: The Web Console.
4. Install a client and pair it
On the device you want to stream to, install the app — Install a Client has the link for every device (Mac, iPhone/iPad/Apple TV, Linux, Windows, Android, Steam Deck), and any Moonlight client works too once you turn GameStream on.
Open the app: your host is already in the list. Select it and connect. Back in the console, the device appears under Pairing → Waiting for approval — click Approve and it's in, no PIN to type. (Prefer a PIN? Click Pair a device in the console and type the 4-digit code into the client.) Pairing happens once; the device reconnects on its own from then on. Details: Pairing & Trust.
5. Stream
Select the host, start streaming. The host creates a display at your device's exact resolution and refresh rate; mouse, keyboard and controllers flow back. On a desktop client the stream takes your mouse and keyboard — Ctrl+Alt+Shift+Q (⌃⌥⇧Q on a Mac) hands them back.
Now that it works
- Launch installed games straight into the stream — Game library (install the plugin for each launcher you use).
- Tune resolution, bitrate, codec and HDR per device — Client settings.
- Copy here, paste there — Shared clipboard. Wake a sleeping host — Wake-on-LAN.
- Run the host headless, with nobody logged in — Running as a service.
- Already running Sunshine or Apollo? Switching from Sunshine.
- Stuck? Troubleshooting starts from the symptom.