adam/foundry
1
0
Fork 0
Code Issues 7 Pull requests 6 Projects 1 Releases Packages Wiki Activity Actions

P1 · End the public-URL hangs (split-horizon DNS vs LAN endpoints) #6

New issue
Open
opened 2026-07-11 19:59:53 -05:00 by adam · 1 comment
adam commented 2026-07-11 19:59:53 -05:00
Owner
Copy link

Priority: P1 · Size: S · Depends on: none

Goal

Make correct media paths and container UIDs a lookup, not a guess, for any media stack deployed on Unraid.

Why (from the 2026-07-11 session)

DroppedNeedle was deployed with guessed library/download paths and with PUID=1001 copied from stacks/media/.env. That value is inert for the legacy arr/media template containers (they actually run as Unraid's default 99:100 — verified: radarr's config and all its media are 99:100) but live for a genuine Dockhand deploy. As UID 1001 the app could not write the 99:100 media tree, so every import failed with permission-denied until fixed to PUID=99/PGID=100 + a chown.

Steps

  • Write docs/reference/unraid-media-conventions.md covering:
    • mediastore layout: media/{music,movies,tv,audiobooks,books}, usenet/{complete,incomplete}.
    • Ownership: everything is nobody:users = 99:100, mode 0775.
    • Rule: media apps deployed via Dockhand MUST use PUID=99 / PGID=100 (and chown -R 99:100 the appdata after any UID change).
    • The single-/data-mount atomic-import rule: library + downloads must be under ONE bind mount so os.rename() doesn't hit EXDEV. Host→container translation: /mnt/user/mediastore → /data.
  • Decide what to do about the misleading sibling .env files (arr, media, ai, data, search all say PUID=1001): fix now to 99/100, or leave with a warning comment until those stacks are Dockhand-adopted. They are a landmine — the day they become real Dockhand deploys they'll fail exactly like DroppedNeedle did.

Acceptance

Doc exists and is linked from CLAUDE.md / relevant skill; the sibling-.env decision is made (fixed, or explicitly deferred with an in-file comment).

Resources

Skills: dockhand-api, unraid-debug, homelab-ssh. Memory: project_dockhand_uid_and_clone_gotchas, project_dockhand_adoption_gap.

**Priority:** P1 · **Size:** S · **Depends on:** none ## Goal Make correct media paths and container UIDs a lookup, not a guess, for any media stack deployed on Unraid. ## Why (from the 2026-07-11 session) DroppedNeedle was deployed with **guessed** library/download paths and with `PUID=1001` copied from `stacks/media/.env`. That value is **inert** for the legacy `arr`/`media` template containers (they actually run as Unraid's default `99:100` — verified: radarr's config and all its media are `99:100`) but **live** for a genuine Dockhand deploy. As UID 1001 the app could not write the `99:100` media tree, so every import failed with permission-denied until fixed to `PUID=99/PGID=100` + a `chown`. ## Steps - Write `docs/reference/unraid-media-conventions.md` covering: - `mediastore` layout: `media/{music,movies,tv,audiobooks,books}`, `usenet/{complete,incomplete}`. - Ownership: everything is `nobody:users` = **`99:100`**, mode `0775`. - **Rule:** media apps deployed via Dockhand MUST use `PUID=99 / PGID=100` (and `chown -R 99:100` the appdata after any UID change). - The single-`/data`-mount atomic-import rule: library + downloads must be under ONE bind mount so `os.rename()` doesn't hit `EXDEV`. Host→container translation: `/mnt/user/mediastore` → `/data`. - Decide what to do about the misleading sibling `.env` files (`arr`, `media`, `ai`, `data`, `search` all say `PUID=1001`): fix now to `99/100`, or leave with a warning comment until those stacks are Dockhand-adopted. They are a **landmine** — the day they become real Dockhand deploys they'll fail exactly like DroppedNeedle did. ## Acceptance Doc exists and is linked from CLAUDE.md / relevant skill; the sibling-`.env` decision is made (fixed, or explicitly deferred with an in-file comment). ## Resources Skills: `dockhand-api`, `unraid-debug`, `homelab-ssh`. Memory: `project_dockhand_uid_and_clone_gotchas`, `project_dockhand_adoption_gap`.
adam commented 2026-07-12 15:31:14 -05:00
Author
Owner
Copy link

Worked 2026-07-12. Two outcomes:

1. The premise no longer holds. This was filed P1 to kill the Pangolin-SSO hang on public *.adamayala.work URLs. Measured today — the hang does not reproduce for Forgejo: public git smart-HTTP, browser, and authed-API all return 200 with no SSO redirect (~0.2s). The June token/auth bypass appears to have been applied. Yesterday's Dockhand clone hang was real but its cause is gone.

2. Documentation half shipped in PR #12 — docs/reference/lan-endpoints.md, a canonical service→address map (LAN / container-to-container / public), wired into CLAUDE.md + skills README. Rationale reframed to what's still true: LAN is faster + tunnel-independent, not "public is broken."

Remaining (downgraded P1 → P3, optional): split-horizon DNS. No DNS resolver runs on Unraid today; standing up AdGuard/Pi-hole for one unified name is a real session for a now-marginal gain. Leaving this issue open to track only that deferred DNS upgrade.

**Worked 2026-07-12.** Two outcomes: **1. The premise no longer holds.** This was filed P1 to kill the Pangolin-SSO hang on public `*.adamayala.work` URLs. Measured today — the hang does **not** reproduce for Forgejo: public git smart-HTTP, browser, and authed-API all return `200` with no SSO redirect (~0.2s). The June token/auth bypass appears to have been applied. Yesterday's Dockhand clone hang was real but its cause is gone. **2. Documentation half shipped** in PR #12 — `docs/reference/lan-endpoints.md`, a canonical service→address map (LAN / container-to-container / public), wired into CLAUDE.md + skills README. Rationale reframed to what's still true: LAN is faster + tunnel-independent, not "public is broken." **Remaining (downgraded P1 → P3, optional):** split-horizon DNS. No DNS resolver runs on Unraid today; standing up AdGuard/Pi-hole for one unified name is a real session for a now-marginal gain. Leaving this issue open to track *only* that deferred DNS upgrade.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
add-qrcode2stl-stack
add-ntfy-stack
fix-stackyard-image-tag
add-stackyard-stack
fix-omniroute-key-docs
add-omniroute-stack
add-ntfy-notifications
feat/obico-ml-detection
docs/lan-endpoints
printing-infra
homeassistant-vm
No results found.
Labels
Clear labels   
lab-honing
Lab-access honing backlog (from 2026-07-11 session review)

No labels
lab-honing
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
adam/foundry#6
No description provided.