From 85fecac401130a3fa6b4537cdeeaa741be2bbe37 Mon Sep 17 00:00:00 2001
From: Trenton H <797416+stumpylog@users.noreply.github.com>
Date: Mon, 16 Mar 2026 22:15:03 -0700
Subject: [PATCH] Fix: don't try to usermod/groupmod when non-root + update
 docs (#12365)

---
 .../s6-overlay/s6-rc.d/init-modify-user/run   | 11 +++++++++
 docs/setup.md                                 | 23 +++++++------------
 2 files changed, 19 insertions(+), 15 deletions(-)

diff --git a/docker/rootfs/etc/s6-overlay/s6-rc.d/init-modify-user/run b/docker/rootfs/etc/s6-overlay/s6-rc.d/init-modify-user/run
index aa617355d..f8430aee2 100755
--- a/docker/rootfs/etc/s6-overlay/s6-rc.d/init-modify-user/run
+++ b/docker/rootfs/etc/s6-overlay/s6-rc.d/init-modify-user/run
@@ -2,6 +2,17 @@
 # shellcheck shell=bash
 declare -r log_prefix="[init-user]"
 
+# When the container is started as a non-root user (e.g. via `user: 999:999`
+# in Docker Compose), usermod/groupmod require root and are meaningless.
+# USERMAP_* variables only apply to the root-started path.
+if [[ -n "${USER_IS_NON_ROOT}" ]]; then
+	if [[ -n "${USERMAP_UID}" || -n "${USERMAP_GID}" ]]; then
+		echo "${log_prefix} WARNING: USERMAP_UID/USERMAP_GID are set but have no effect when the container is started as a non-root user"
+	fi
+	echo "${log_prefix} Running as non-root user ($(id --user):$(id --group)), skipping UID/GID remapping"
+	exit 0
+fi
+
 declare -r usermap_original_uid=$(id -u paperless)
 declare -r usermap_original_gid=$(id -g paperless)
 declare -r usermap_new_uid=${USERMAP_UID:-$usermap_original_uid}
diff --git a/docs/setup.md b/docs/setup.md
index 5795968ef..3b84fd729 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -140,24 +140,17 @@ a [superuser](usage.md#superusers) account.
 
 !!! warning
 
-    It is currently not possible to run the container rootless if additional languages are specified via `PAPERLESS_OCR_LANGUAGES`.
+    It is not possible to run the container rootless if additional languages are specified via `PAPERLESS_OCR_LANGUAGES`.
 
-If you want to run Paperless as a rootless container, make this
-change in `docker-compose.yml`:
+If you want to run Paperless as a rootless container, set `user:` in `docker-compose.yml` to the UID and GID of your host user (use `id -u` and `id -g` to find these values). The container process starts directly as that user with no internal privilege remapping:
 
-- Set the `user` running the container to map to the `paperless`
-  user in the container. This value (`user_id` below) should be
-  the same ID that `USERMAP_UID` and `USERMAP_GID` are set to in
-  `docker-compose.env`. See `USERMAP_UID` and `USERMAP_GID`
-  [here](configuration.md#docker).
+```yaml
+webserver:
+  image: ghcr.io/paperless-ngx/paperless-ngx:latest
+  user: '1000:1000'
+```
 
-Your entry for Paperless should contain something like:
-
-> ```
-> webserver:
->   image: ghcr.io/paperless-ngx/paperless-ngx:latest
->   user: <user_id>
-> ```
+Do not combine this with `USERMAP_UID` or `USERMAP_GID`, which are intended for the non-rootless case described in step 3.
 
 **File systems without inotify support (e.g. NFS)**