[PR #67] [MERGED] Re-own Wolf app state when the run UID changes (fixes #66) #73

New issue

Closed

opened 2026-10-15 12:55:23 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-15 12:55:23 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/games-on-whales/unraid-plugin/pull/67
Author: @JBailes
Created: 7/30/2026
Status: ✅ Merged
Merged: 7/30/2026
Merged by: @JBailes

Base: main ← Head: fix/issue-66-app-state-ownership

📝 Commits (1)

413ec09 Re-own Wolf app state when the run UID changes (fixes #66)

📊 Changes

2 files changed (+93 additions, -4 deletions)

View changed files

📝 docs/FAQ.md (+38 -0)
📝 scripts/deploy.sh (+55 -4)

📄 Description

Problem

#62 set WOLF_DEFAULT_RUN_UID=99 / WOLF_DEFAULT_RUN_GID=100 so apps run as Unraid's nobody:users. On existing installs this stops apps from starting — Steam in particular: the container comes up, sway and waybar appear, Big Picture never does (#66).

Wolf bind-mounts <appdata>/profile-data/<profile>/<app> as /home/retro in each app container and runs it as PUID/PGID (sessions/common.cpp:49,66). Nothing re-owns state that is already on disk:

Wolf only create_directories on the state folder, it never chowns it (sessions/lobbies.cpp:131).
The gow base image's 10-setup_user.sh does chown "$PUID:$PGID" "$HOME" — top level only, not recursive.

So every app's dotfiles, Steam library and Decky state stayed owned by 1000 while the process became 99, and Steam dies during startup. The reporter's log stops exactly there:

Setting default user uid=99(retro) gid=100(retro)
steam.sh[226]: Running Steam on ubuntu 25.04 64-bit
setup.sh[317]: Steam runtime environment up-to-date!

There is a second trap behind it: per Wolf's docs, WOLF_DEFAULT_RUN_UID/GID apply only to newly paired clients — clients paired earlier keep the UID saved in config.toml. Re-owning the folders alone would break anyone whose saved run_uid is still 1000.

Fix

scripts/deploy.sh:

migrate_app_state_ownership — chown -R 99:100 over <appdata>/profile-data, recorded in cfg/.run-ids so the walk only happens when the UID/GID pair actually changes. These trees hold whole Steam libraries; walking them on every Apply would be slow for no reason.
normalize_client_run_ids — rewrites saved run_uid/run_gid in config.toml so already-paired clients run as the user the state folders are now owned by, instead of a stale 1000 that can no longer write them.
WOLF_RUN_UID/WOLF_RUN_GID become a single constant that both compose writers read, so the value handed to Wolf can't drift from the value the migration chowns to.

docs/FAQ.md gets an entry with the log signature, a find check, and the fix (click Install; the first re-deploy is slow, later ones are stamped and skip).

Existing users recover by re-deploying from Settings > Games on Whales. New installs are unaffected — profile-data doesn't exist yet, so the migration is a no-op and no false stamp is written.

Verification

bash -n clean.
12/12 pass in a functional test of both new functions against real directory trees and TOML fixtures: deep re-own, stamp written, stamped re-run is a no-op, stale stamp re-migrates, fresh install leaves no stamp, both table and inline-table TOML rewritten, unrelated keys untouched, missing config a no-op. Compose rendering confirmed to emit 99/100.
Not verified: that Steam actually launches afterwards — no Unraid host or GPU available. The causal chain is read off Wolf's and gow's source rather than reproduced, and the test chowns to a uid/gid pair an unprivileged user can set rather than literally 99:100. Worth a confirmation from the reporter on a real box.

Out of scope, but noted

<appdata>/steam is still created by setup_appdata_dirs but is unused by current Wolf, which uses profile-data.
compatibilitytools.d is still chowned 1000:1000 for wolf-den. Nothing in this repo mounts it into an app container, but if Proton installs ever land there for the Steam app it will hit the same UID mismatch.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/games-on-whales/unraid-plugin/pull/67 **Author:** [@JBailes](https://github.com/JBailes) **Created:** 7/30/2026 **Status:** ✅ Merged **Merged:** 7/30/2026 **Merged by:** [@JBailes](https://github.com/JBailes) **Base:** `main` ← **Head:** `fix/issue-66-app-state-ownership` --- ### 📝 Commits (1) - [`413ec09`](https://github.com/games-on-whales/unraid-plugin/commit/413ec09033e72a6bee76f7b14270bec8b9658606) Re-own Wolf app state when the run UID changes (fixes #66) ### 📊 Changes **2 files changed** (+93 additions, -4 deletions) <details> <summary>View changed files</summary> 📝 `docs/FAQ.md` (+38 -0) 📝 `scripts/deploy.sh` (+55 -4) </details> ### 📄 Description ## Problem #62 set `WOLF_DEFAULT_RUN_UID=99` / `WOLF_DEFAULT_RUN_GID=100` so apps run as Unraid's `nobody:users`. On existing installs this stops apps from starting — Steam in particular: the container comes up, sway and waybar appear, Big Picture never does (#66). Wolf bind-mounts `<appdata>/profile-data/<profile>/<app>` as `/home/retro` in each app container and runs it as `PUID`/`PGID` (`sessions/common.cpp:49,66`). Nothing re-owns state that is already on disk: - Wolf only `create_directories` on the state folder, it never chowns it (`sessions/lobbies.cpp:131`). - The gow base image's `10-setup_user.sh` does `chown "$PUID:$PGID" "$HOME"` — **top level only**, not recursive. So every app's dotfiles, Steam library and Decky state stayed owned by 1000 while the process became 99, and Steam dies during startup. The reporter's log stops exactly there: ```text Setting default user uid=99(retro) gid=100(retro) steam.sh[226]: Running Steam on ubuntu 25.04 64-bit setup.sh[317]: Steam runtime environment up-to-date! ``` There is a second trap behind it: per Wolf's docs, `WOLF_DEFAULT_RUN_UID/GID` apply **only to newly paired clients** — clients paired earlier keep the UID saved in `config.toml`. Re-owning the folders alone would break anyone whose saved `run_uid` is still 1000. ## Fix `scripts/deploy.sh`: - **`migrate_app_state_ownership`** — `chown -R 99:100` over `<appdata>/profile-data`, recorded in `cfg/.run-ids` so the walk only happens when the UID/GID pair actually changes. These trees hold whole Steam libraries; walking them on every Apply would be slow for no reason. - **`normalize_client_run_ids`** — rewrites saved `run_uid`/`run_gid` in `config.toml` so already-paired clients run as the user the state folders are now owned by, instead of a stale 1000 that can no longer write them. - `WOLF_RUN_UID`/`WOLF_RUN_GID` become a single constant that both compose writers read, so the value handed to Wolf can't drift from the value the migration chowns to. `docs/FAQ.md` gets an entry with the log signature, a `find` check, and the fix (click **Install**; the first re-deploy is slow, later ones are stamped and skip). Existing users recover by re-deploying from **Settings > Games on Whales**. New installs are unaffected — `profile-data` doesn't exist yet, so the migration is a no-op and no false stamp is written. ## Verification - `bash -n` clean. - 12/12 pass in a functional test of both new functions against real directory trees and TOML fixtures: deep re-own, stamp written, stamped re-run is a no-op, stale stamp re-migrates, fresh install leaves no stamp, both table and inline-table TOML rewritten, unrelated keys untouched, missing config a no-op. Compose rendering confirmed to emit `99`/`100`. - **Not verified:** that Steam actually launches afterwards — no Unraid host or GPU available. The causal chain is read off Wolf's and gow's source rather than reproduced, and the test chowns to a uid/gid pair an unprivileged user can set rather than literally 99:100. Worth a confirmation from the reporter on a real box. ## Out of scope, but noted - `<appdata>/steam` is still created by `setup_appdata_dirs` but is unused by current Wolf, which uses `profile-data`. - `compatibilitytools.d` is still chowned `1000:1000` for wolf-den. Nothing in this repo mounts it into an app container, but if Proton installs ever land there for the Steam app it will hit the same UID mismatch. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-15 12:55:23 +00:00