Skip to content

Add PUID/PGID support for NAS volume permissions#95

Merged
jasonmadigan merged 3 commits into
mainfrom
fix/94-puid-pgid-volume-permissions
Jun 19, 2026
Merged

Add PUID/PGID support for NAS volume permissions#95
jasonmadigan merged 3 commits into
mainfrom
fix/94-puid-pgid-volume-permissions

Conversation

@jasonmadigan

Copy link
Copy Markdown
Collaborator

Closes #94

Adds PUID/PGID env var support to the entrypoint for Unraid/TrueNAS deployments where host volumes are owned by non-1000 UIDs.

Three code paths:

  • Non-root (--user flag): skips remapping, runs as provided user
  • Root, no PUID/PGID: defaults to 1000:1000, identical to previous releases
  • Root, PUID/PGID set: remaps tracefinity user, chowns storage, drops privileges via gosu

Default behaviour is unchanged -- existing users unaffected.

Unraid and TrueNAS pass PUID/PGID env vars instead of --user.
The hardcoded USER tracefinity (UID 1000) caused permission
denied errors when host volumes are owned by a different user.

- Remove USER directive; entrypoint starts as root and drops
  privileges via gosu after remapping
- Add PUID/PGID handling: groupmod/usermod to remap the
  tracefinity user, chown /app/storage when ownership differs
- Preserve --user flag path: non-root entrypoint skips
  remapping and runs directly (existing behaviour)
- Default (no env vars) is identical to previous releases

Fixes #94

Signed-off-by: Jason Madigan <[email protected]>
The root cause: supervisord re-opens /dev/stdout and /dev/stderr as
filesystem paths for child log capture. These resolve through
/proc/self/fd/{1,2} which are owned by root with mode 0200. After gosu
drops to UID 1000, supervisor's open() calls fail with EACCES.

Fix: let supervisord run as root (it can open the log paths) and use
supervisor's own user= directive on each [program:] section to drop
privileges per-child. The entrypoint still handles PUID/PGID remapping
and storage ownership, but no longer uses gosu for the final exec.

The --user flag path is unaffected (supervisor runs as the given UID,
user=tracefinity is a no-op when already that UID).

Signed-off-by: Jason Madigan <[email protected]>
The supervisor config shipped with user=tracefinity baked into each
[program:xxx] section. This works when supervisord runs as root (it
can setuid to the target user), but breaks with --user flag because
a non-root supervisor cannot call setuid at all, causing "Can't drop
privilege as nonroot user" and immediate exit.

Fix: ship the config WITHOUT any user= directives (compatible with
--user mode), and have the entrypoint inject user=root in [supervisord]
plus user=tracefinity in each [program:xxx] only when running as root.
The injection is idempotent (skipped if user= already present).

All three deployment modes now work:
- Default (root, no PUID/PGID): children run as tracefinity (1000:1000)
- PUID/PGID (root, remapped): children run as remapped tracefinity
- --user flag (non-root): all processes run as the specified UID

Signed-off-by: Jason Madigan <[email protected]>
@jasonmadigan
jasonmadigan merged commit f90aa67 into main Jun 19, 2026
1 check passed
@jasonmadigan
jasonmadigan deleted the fix/94-puid-pgid-volume-permissions branch June 19, 2026 15:07
shanetinklenberg pushed a commit to shanetinklenberg/tracefinity that referenced this pull request Jun 28, 2026
* Add PUID/PGID support for NAS volume permissions (tracefinity#94)

Unraid and TrueNAS pass PUID/PGID env vars instead of --user.
The hardcoded USER tracefinity (UID 1000) caused permission
denied errors when host volumes are owned by a different user.

- Remove USER directive; entrypoint starts as root and drops
  privileges via gosu after remapping
- Add PUID/PGID handling: groupmod/usermod to remap the
  tracefinity user, chown /app/storage when ownership differs
- Preserve --user flag path: non-root entrypoint skips
  remapping and runs directly (existing behaviour)
- Default (no env vars) is identical to previous releases

Fixes tracefinity#94

Signed-off-by: Jason Madigan <[email protected]>

* Fix supervisor EACCES when entrypoint drops privileges via gosu

The root cause: supervisord re-opens /dev/stdout and /dev/stderr as
filesystem paths for child log capture. These resolve through
/proc/self/fd/{1,2} which are owned by root with mode 0200. After gosu
drops to UID 1000, supervisor's open() calls fail with EACCES.

Fix: let supervisord run as root (it can open the log paths) and use
supervisor's own user= directive on each [program:] section to drop
privileges per-child. The entrypoint still handles PUID/PGID remapping
and storage ownership, but no longer uses gosu for the final exec.

The --user flag path is unaffected (supervisor runs as the given UID,
user=tracefinity is a no-op when already that UID).

Signed-off-by: Jason Madigan <[email protected]>

* Fix supervisor child processes running as root instead of tracefinity

The supervisor config shipped with user=tracefinity baked into each
[program:xxx] section. This works when supervisord runs as root (it
can setuid to the target user), but breaks with --user flag because
a non-root supervisor cannot call setuid at all, causing "Can't drop
privilege as nonroot user" and immediate exit.

Fix: ship the config WITHOUT any user= directives (compatible with
--user mode), and have the entrypoint inject user=root in [supervisord]
plus user=tracefinity in each [program:xxx] only when running as root.
The injection is idempotent (skipped if user= already present).

All three deployment modes now work:
- Default (root, no PUID/PGID): children run as tracefinity (1000:1000)
- PUID/PGID (root, remapped): children run as remapped tracefinity
- --user flag (non-root): all processes run as the specified UID

Signed-off-by: Jason Madigan <[email protected]>

---------

Signed-off-by: Jason Madigan <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

USER tracefinity in v0.5.0 breaks volume permissions for Unraid and TrueNAS templates

1 participant