docs: restructure host setup by distro, configuration by compositor

Split the docs' single distro×desktop axis (ubuntu-gnome / ubuntu-kde / fedora-kde) into two, which deduplicates the shared mechanics and scales to distros that run several desktops (Arch): - Install the host — per distro/OS (ubuntu, fedora, arch, bazzite, steamos-host, windows-host): GPU driver + package + input group, then a canonical "Configure your desktop" funnel. - Configure your desktop — per compositor (kde, gnome, gamescope, sway): host.env, compositor quirks, the headless session, and starting the host. New shared web-console page (enable · login password · arm pairing) removes the console/password block that was copy-pasted across all seven host pages. Merged ubuntu-gnome + ubuntu-kde into ubuntu; renamed fedora-kde to fedora; kept bazzite and steamos-host as dedicated appliance guides (trimmed of duplication). Moved the KWin headless session, the GNOME EGL/lock traps, and the gamescope attach/managed model out of the distro pages onto their compositor pages. Fixed while restructuring: distro-specific paths on kde (kde-desktop-setup.sh is Fedora/Bazzite-only; the .deb ships host.env.kde under /usr/share/punktfunk-host), the interactive "start the host" step that was lost in the merge, sway over-claiming Hyprland, and a pre-existing broken anchor in how-it-works. Removal of the three old pages was captured by the preceding commit 8ebb614 (a concurrent commit swept up the staged git-rm); the net docs tree is correct. Fumadocs build + internal link/anchor check green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-05 21:04:31 +00:00
parent 8ebb61400c
commit 69fcb6e0b1
21 changed files with 854 additions and 192 deletions
@@ -0,0 +1,73 @@
+---
+title: The Web Console
+description: Enable the punktfunk browser console, read or change its login password, and arm PIN pairing.
+---
+
+The web console is the browser UI for a punktfunk host — live status, paired devices, and the PIN
+pairing flow. It ships as the **`punktfunk-web`** systemd user unit on Linux and the **`PunktfunkWeb`**
+task on Windows, and serves on **`http://<host-ip>:47992`**. The host's own management API stays
+loopback-only behind it, so the console is the one surface you expose on the LAN.
+
+> New here? Read [Security & Safe Use](/docs/security) first — a streaming host is remote control of
+> the machine, so keep it on a trusted LAN or VPN and require pairing.
+
+## Enable the console
+
+- **Linux packages (apt / RPM / Bazzite):** `punktfunk-host` recommends `punktfunk-web`, so your
+  package manager pulls it in. Enable and start it as your desktop user, then open the URL:
+
+  ```sh
+  systemctl --user enable --now punktfunk-web
+  # then browse to http://<host-ip>:47992
+  ```
+
+- **Windows host:** the installer sets up the console, its runtime, and the `PunktfunkWeb` task and
+  starts it at boot. There is nothing to enable — open `http://<this-PC>:47992`.
+
+- **SteamOS host:** the install script builds and starts the console as a user service for you. It
+  prints the URL when it finishes.
+
+## Login password
+
+The console is password-protected. Where that password lives and how you change it depends on the
+host platform.
+
+**Linux packages (apt / RPM / Bazzite).** On first start `punktfunk-web-init` generates a random
+password and saves it to `~/.config/punktfunk/web-password` (as `PUNKTFUNK_UI_PASSWORD=…`). Read it
+back from the init service's journal or straight from the file:
+
+```sh
+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, edit that file (`PUNKTFUNK_UI_PASSWORD=<your-password>`) and restart the console:
+`systemctl --user restart punktfunk-web`.
+
+**SteamOS host.** Same idea, but the install script writes the generated password to
+`~/.config/punktfunk/web.env` and prints it at the end of the install run:
+
+```sh
+sed -n 's/^PUNKTFUNK_UI_PASSWORD=//p' ~/.config/punktfunk/web.env
+```
+
+Edit that file and `systemctl --user restart punktfunk-web` to change it.
+
+**Windows host.** You choose the password during install — a secure random default is pre-filled and
+shown again on the installer's final page. It's stored in `%ProgramData%\punktfunk\web-password` (as
+`PUNKTFUNK_UI_PASSWORD=…`), readable only by Administrators and SYSTEM. To change it, edit the file
+and restart the task in an **elevated** PowerShell:
+
+```powershell
+notepad "$env:ProgramData\punktfunk\web-password"   # set PUNKTFUNK_UI_PASSWORD=<your-password>
+schtasks /End /TN PunktfunkWeb; schtasks /Run /TN PunktfunkWeb
+```
+
+Forgot it? See [Forgot your Password?](/docs/forgot-password).
+
+## Arm pairing
+
+The host **requires PIN pairing** by default (secure on a LAN). To connect the first time, open the
+console, log in, and go to **Devices → arm pairing**. The host displays a 4-digit PIN — enter it on
+your [client](/docs/clients) to pair. See [Pairing & Trust](/docs/pairing) for the full trust model
+and how to approve or remove devices later.