Skip to content

Release v3.7.8 - Optional PUID/PGID ownership remap for Unraid/home servers

Choose a tag to compare

@pacnpal pacnpal released this 13 May 13:27
· 479 commits to latest since this release
86abb33

✨ New Features

  • Added optional PUID/PGID support for container file ownership mapping. On startup, the entrypoint now accepts PUID/PGID (default 999:999) and remaps the internal converter account before launching the app. This aligns output ownership with host conventions used by Unraid and other home-server setups.
  • Safe GID fallback for common Unraid defaults. When PGID points to a GID that already exists in the base image (for example 100), the startup remap falls back from groupmod to usermod -g so converter is reassigned to the existing group instead of failing.
  • Privilege drop now handled by gosu in entrypoint. The image installs gosu, keeps startup as root only long enough to perform optional remapping, then immediately re-execs as converter.

🔧 Internal

  • Dockerfile now installs gosu and no longer sets USER converter at build time.
  • entrypoint.sh now:
    • validates PUID/PGID are numeric,
    • remaps converter UID/GID when needed,
    • preserves old behavior when env vars are unset (999:999),
    • drops privileges with exec gosu converter "$0" "$@".

📚 Documentation

  • Updated README.md, DOCKER-COMPOSE.md, DEPLOYMENT.md, and compose examples to document PUID/PGID as an optional runtime ownership setting.

⚠️ Upgrade Notes

  • No action required. With PUID/PGID unset the container behaves exactly as before (converter:converter at 999:999).
  • To get host-correct ownership on Unraid: set PUID=99 and PGID=100. On other home-server setups, set them to the UID/GID of the user that owns the host directory you bind-mount.
  • If you already pin --user on docker run / compose, the container starts non-root and the remap is skipped. A warning is emitted in that case so the no-op is visible.

Closes #64. Thanks @humaintenance for the well-scoped feature request and the working entrypoint snippet.