unom/punktfunk
10
0
Fork 4
Code Issues 15 Pull Requests 1 Actions 1 Packages Projects 1 Releases 60 Wiki Activity

feat/installer: make the universal install.sh ask about intent, not internals — and pick sane per-distro defaults #431

New Issue
Closed
opened 2026-08-28 20:10:47 +00:00 by enricobuehler · 0 comments
enricobuehler commented 2026-08-28 20:10:47 +00:00
Owner
Copy Link
Copy Source

scripts/install.sh — the guided universal host installer, still labelled PREVIEW — asks roughly the
right number of questions, but the wrong kind. Every prompt names a mechanism the user has to
already understand, and every one defaults to n no matter which distro was detected. So a user who
holds Enter, or anyone on the curl … | sh path (no tty ⇒ YES=1, scripts/install.sh:93), lands on
a configuration that is wrong for whole classes of machine — including the two distros our own docs
target hardest.

What it asks today

line prompt default
scripts/install.sh:337 "Also join the punktfunk group? … by granting usbip attach" n
scripts/install.sh:347 "Also serve stock Moonlight clients (GameStream compat)?" n
scripts/install.sh:354 "Allow the shared clipboard on this host?" n
scripts/install.sh:392 "Start the host at boot even with nobody logged in (linger)?" n
scripts/install.sh:264 "Install punktfunk-web, punktfunk-scripting too?" (Arch only) y
scripts/install.sh:315 "Move the management API to $MGMT_PORT?" (on conflict) y

Two problems, and they compound.

1. The prompts name our internals, not the user's intent

"GameStream compat", "the punktfunk group", "usbip attach", "linger" are answers. A user who does
not already know the architecture cannot evaluate them, so they take the default. What we actually
want to know is what they intend to do:

  • "Will you connect with Moonlight, Artemis, or another third-party client? (Punktfunk's own apps
    don't need this.)"     → sets PUNKTFUNK_GAMESTREAM and the punktfunk-gamestream firewall service.
  • "Do you want the full controller — paddles, trackpads, gyro?" → the punktfunk group.
  • "Is this a box you stream from and never log into, or a machine you sit at?" → linger.
  • "Share the clipboard between this host and your clients?" is already intent-framed. Keep it.

Same code paths, same env vars, same prompt count. Only the wording changes — plus the default
behind it.

2. n is the wrong default where it matters most, and our own docs say so

The punktfunk group is the sharpest case. It is not an exotic opt-in:

  • docs-site/content/docs/gamescope.md:57 — "Join the punktfunk group on any box you stream Game
    Mode from.    "     Unconditional. Without it the virtual Steam Deck pad arrives as a plain Xbox 360
    controller.
  • docs-site/content/docs/bazzite.mdx:35 lists sudo usermod -aG punktfunk "$USER" as a normal
    step 2    , not an aside.

Meanwhile scripts/install.sh:337 defaults it to no and buries the reason behind a doc anchor. A
Bazzite or Nobara user — i.e. someone whose entire reason to run us is a couch/HTPC setup with a
Deck-shaped pad — takes the default, gets a degraded controller, and files the support question we
could have prevented. Under --yes they never see the prompt at all.

Linger repeats the pattern: docs-site/content/docs/bazzite.mdx:42 says "Bazzite hosts are usually
headless, so enable the services and linger" — while scripts/install.sh:392 defaults linger to
no.

Everything needed to fix this is already computed by the time we ask. ID, ID_LIKE and FAMILY are
known at scripts/install.sh:159-176; CONFLICT at scripts/install.sh:312:

  • FAMILY=sysext / ujust present / Bazzite / Nobara → punktfunk group Y, linger Y
  • CONFLICT=1 (Sunshine/Apollo/Vibeshine found) → the user demonstrably owns Moonlight-family
    clients, so the GameStream question should default Y, not n
  • no graphical seat (installed over SSH) → linger Y

Scope

  • Reword the prompts in intent terms. Keep every flag and PUNKTFUNK_INSTALL_* env twin exactly
    as-is     — this is wording plus default selection, not a new options model, and scripted installs
    must not break.
  • Derive the defaults from the already-detected ID / FAMILY / CONFLICT, and say why when one
    flips: "Bazzite detected — joining the punktfunk group so the virtual Steam Deck pad works [Y/n]".
    A visible, overridable default beats a silent one.
  • Print a one-screen summary of the resulting choices before the first sudo, so an interactive
    user sees what they agreed to and a --yes run is auditable in the log.
  • Reconcile the per-distro doc pages with whatever the installer now defaults to, so the two stop
    contradicting each other. (scripts/ci/check-docs-drift.sh gate 6 pins only the install snippets
    to data/platforms.json; none of this touches those lines — the group/linger prose is ungated,
    which is how the drift got in.)
  • POSIX sh, no TUI, no new dependency. --yes stays the unattended path; it just picks better
    answers.
  • Extend .gitea/workflows/installer-smoke.yml with a case per family asserting the derived defaults.
    --dry-run plus the PUNKTFUNK_INSTALL_OS_RELEASE override at scripts/install.sh:155 already
    make this cheap — that hook exists for exactly this.

Out of scope

Windows, NixOS, SteamOS and the clients keep their own paths — the script already stops and points at
them. Not proposing a menu, a TUI, or a config file.

Related: #296 (docs overhaul). Distinct from the Omarchy installer gaps, which are bugs in a
different installer.

`scripts/install.sh` — the guided universal host installer, still labelled PREVIEW — asks roughly the right *number* of questions, but the wrong *kind*. Every prompt names a mechanism the user has to already understand, and every one defaults to `n` no matter which distro was detected. So a user who holds Enter, or anyone on the `curl … | sh` path (no tty ⇒ `YES=1`, `scripts/install.sh:93`), lands on a configuration that is wrong for whole classes of machine — including the two distros our own docs target hardest. ## What it asks today | line | prompt | default | |---|---|---| | `scripts/install.sh:337` | "Also join the **punktfunk group**? … by granting usbip attach" | n | | `scripts/install.sh:347` | "Also serve stock Moonlight clients (**GameStream compat**)?" | n | | `scripts/install.sh:354` | "Allow the shared clipboard on this host?" | n | | `scripts/install.sh:392` | "Start the host at boot even with nobody logged in (**linger**)?" | n | | `scripts/install.sh:264` | "Install punktfunk-web, punktfunk-scripting too?" (Arch only) | y | | `scripts/install.sh:315` | "Move the management API to `$MGMT_PORT`?" (on conflict) | y | Two problems, and they compound. ## 1. The prompts name our internals, not the user's intent "GameStream compat", "the punktfunk group", "usbip attach", "linger" are *answers*. A user who does not already know the architecture cannot evaluate them, so they take the default. What we actually want to know is what they intend to do: - **"Will you connect with Moonlight, Artemis, or another third-party client? (Punktfunk's own apps don't need this.)"** → sets `PUNKTFUNK_GAMESTREAM` and the `punktfunk-gamestream` firewall service. - **"Do you want the full controller — paddles, trackpads, gyro?"** → the `punktfunk` group. - **"Is this a box you stream from and never log into, or a machine you sit at?"** → linger. - **"Share the clipboard between this host and your clients?"** is already intent-framed. Keep it. Same code paths, same env vars, same prompt count. Only the wording changes — plus the default behind it. ## 2. `n` is the wrong default where it matters most, and our own docs say so The `punktfunk` group is the sharpest case. It is not an exotic opt-in: - `docs-site/content/docs/gamescope.md:57` — *"**Join the `punktfunk` group on any box you stream Game Mode from.**"* Unconditional. Without it the virtual Steam Deck pad arrives as a plain Xbox 360 controller. - `docs-site/content/docs/bazzite.mdx:35` lists `sudo usermod -aG punktfunk "$USER"` as a **normal step 2**, not an aside. Meanwhile `scripts/install.sh:337` defaults it to **no** and buries the reason behind a doc anchor. A Bazzite or Nobara user — i.e. someone whose entire reason to run us is a couch/HTPC setup with a Deck-shaped pad — takes the default, gets a degraded controller, and files the support question we could have prevented. Under `--yes` they never see the prompt at all. Linger repeats the pattern: `docs-site/content/docs/bazzite.mdx:42` says *"Bazzite hosts are usually headless, so enable the services **and** linger"* — while `scripts/install.sh:392` defaults linger to **no**. Everything needed to fix this is already computed by the time we ask. `ID`, `ID_LIKE` and `FAMILY` are known at `scripts/install.sh:159-176`; `CONFLICT` at `scripts/install.sh:312`: - `FAMILY=sysext` / `ujust` present / Bazzite / Nobara → punktfunk group **Y**, linger **Y** - `CONFLICT=1` (Sunshine/Apollo/Vibeshine found) → the user demonstrably owns Moonlight-family clients, so the GameStream question should default **Y**, not n - no graphical seat (installed over SSH) → linger **Y** ## Scope - Reword the prompts in intent terms. **Keep every flag and `PUNKTFUNK_INSTALL_*` env twin exactly as-is** — this is wording plus default selection, not a new options model, and scripted installs must not break. - Derive the defaults from the already-detected `ID` / `FAMILY` / `CONFLICT`, and say *why* when one flips: `"Bazzite detected — joining the punktfunk group so the virtual Steam Deck pad works [Y/n]"`. A visible, overridable default beats a silent one. - Print a one-screen summary of the resulting choices **before the first `sudo`**, so an interactive user sees what they agreed to and a `--yes` run is auditable in the log. - Reconcile the per-distro doc pages with whatever the installer now defaults to, so the two stop contradicting each other. (`scripts/ci/check-docs-drift.sh` gate 6 pins only the *install snippets* to `data/platforms.json`; none of this touches those lines — the group/linger prose is ungated, which is how the drift got in.) - POSIX `sh`, no TUI, no new dependency. `--yes` stays the unattended path; it just picks better answers. - Extend `.gitea/workflows/installer-smoke.yml` with a case per family asserting the derived defaults. `--dry-run` plus the `PUNKTFUNK_INSTALL_OS_RELEASE` override at `scripts/install.sh:155` already make this cheap — that hook exists for exactly this. ## Out of scope Windows, NixOS, SteamOS and the clients keep their own paths — the script already stops and points at them. Not proposing a menu, a TUI, or a config file. Related: #296 (docs overhaul). Distinct from the Omarchy installer gaps, which are bugs in a different installer.
luxus self-assigned this 2026-08-28 22:18:12 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
FernandoMX FlipperDan HitFrostbite bluelightspecial enricobuehler (Enrico Bühler) kszlim luxus nannku neoney sonar
No Assignees luxus
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: unom/punktfunk#431