Support explicit non-root Docker users

[ImAurum11]

Description

I went through the previous attempts and the rootless guide before working on this. I ended up keeping the current image behavior unchanged and relying on Docker's own user: UID:GID support instead of adding another PUID/PGID entrypoint.

The main thing in the way was Stash trying to look up the current user. Numeric container users don't always exist in /etc/passwd, so Stash now uses HOME first and falls back to the previous lookup when needed. The compose example shows the matching home and config settings without changing anything for existing installations.

CUDA actually needed a small exception because its optional NVIDIA patch writes to system directories. It still works exactly as before when running as root, while a non-root container skips the patch and starts Stash normally.

Related Issue

Closes #684.

Testing

I tested this with UID/GID 12345:23456 and no matching user entry, and success! Stash started in the official image, responded over HTTP, and wrote files with the expected ownership.

The Go tests, configuration tests, Compose validation, shell checks and full backend build also pass. Should be good to go.

Screenshots

Not applicable.

Checklist

• I have read and understood the Contributing document.
• I have read and understood the AI Usage Policy document.
• I have made corresponding changes to the documentation (if applicable).

AI Usage Disclosure

• I have used AI tools to assist with this pull request, and I have disclosed the tools and how I used them below.

I used Codex while researching the previous attempts, tidying/tying up the implementation and running some tests. I reviewed all of its changes and take full responsibility for them.

On a side note, sorry again for the earlier PR missing the template, sometimes I skip through reading unintentionally. Appreciate your patience.

[aserv92]

I also have concerns about running stash as a user that does not actually exist from the containers perspective.

[aserv92]

The current implementation will re-run stash (one more time) when the user ID is 0 (root) and stash exits with exit code 0 on the first run.

Suggested change

	if [ "$(id -u)" -eq 0 ]; then
	exec /usr/local/bin/nvidia-patch-entrypoint.sh "$@"
	fi
	exec "$@"
	if [ "$(id -u)" -eq 0 ]; then
	exec /usr/local/bin/nvidia-patch-entrypoint.sh "$@"
	else
	exec "$@"
	fi

or

Suggested change

	if [ "$(id -u)" -eq 0 ]; then
	exec /usr/local/bin/nvidia-patch-entrypoint.sh "$@"
	fi
	exec "$@"
	if [ "$(id -u)" -eq 0 ]; then
	exec /usr/local/bin/nvidia-patch-entrypoint.sh "$@"
	exit $?
	fi
	exec "$@"

[aserv92]

I recommend using a better name for the entry point as both entry points are docker entry points.

[ImAurum11]

These are interesting suggestions ngl, appreciate you taking the time. Sorry I didn't see them earlier, GitHub didn't really notify me in my inbox or email haha.

I took the naming point and changed the wrapper to cuda-entrypoint.sh, which makes its role clearer next to nvidia-patch-entrypoint.sh. I also clarified in the docs that the numeric UID doesn't need an /etc/passwd entry as long as HOME points to a writable directory. That's the exact setup I tested with UID/GID 12345:23456.

I took another look at the exec part, but I left it as-is because it can't run Stash twice. The first exec replaces the wrapper with the NVIDIA script, and that script ends with exec "$@". The if/else version would behave the same, while the other suggestion has an unreachable exit after exec.

Thanks again.