From f589fe53e84aaa6c15e0d939171706bd9961f784 Mon Sep 17 00:00:00 2001 From: Henning Dickten Date: Sat, 18 Oct 2025 22:13:34 +0200 Subject: [PATCH 1/2] feat: rootless - switch to user 1000:1000 --- Dockerfile | 11 ++++++++--- README.md | 19 +++++++++++++++++++ docker-compose.yml | 6 ++++++ entrypoint.sh | 28 ++++++++++++++++++++++++++++ 4 files changed, 61 insertions(+), 3 deletions(-) create mode 100755 entrypoint.sh diff --git a/Dockerfile b/Dockerfile index 89656618..1f10adeb 100644 --- a/Dockerfile +++ b/Dockerfile @@ -88,7 +88,8 @@ ENV GIN_MODE=release # Install necessary runtime dependencies RUN apk add --no-cache \ - ca-certificates + ca-certificates \ + su-exec # Set the working directory inside the container WORKDIR /app/ @@ -96,11 +97,15 @@ WORKDIR /app/ # Copy the Go binary from the builder stage COPY --from=builder /app/paperless-gpt . +# Copy the entrypoint script +COPY entrypoint.sh . +RUN chmod +x ./entrypoint.sh + # Copy the prompt templates COPY default_prompts/ /app/default_prompts/ # Expose the port the app runs on EXPOSE 8080 -# Command to run the binary -CMD ["/app/paperless-gpt"] +# Set the entrypoint +ENTRYPOINT ["./entrypoint.sh"] diff --git a/README.md b/README.md index 9454bdf2..970f3a34 100644 --- a/README.md +++ b/README.md @@ -531,6 +531,8 @@ For best results with the enhanced OCR features: | Variable | Description | Required | Default | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------- | +| `PUID` | User ID to run the container as. See [Running as a Non-Root User](#running-as-a-non-root-user). | No | 1000 | +| `PGID` | Group ID to run the container as. See [Running as a Non-Root User](#running-as-a-non-root-user). | No | 1000 | | `PAPERLESS_BASE_URL` | URL of your paperless-ngx instance (e.g. `http://paperless-ngx:8000`). | Yes | | | `PAPERLESS_API_TOKEN` | API token for paperless-ngx. Generate one in paperless-ngx admin. | Yes | | | `PAPERLESS_PUBLIC_URL` | Public URL for Paperless (if different from `PAPERLESS_BASE_URL`). | No | | @@ -935,6 +937,23 @@ Common issues and solutions: --- +### Running as a Non-Root User + +By default, the Docker container runs as a non-root user for enhanced security. You can control the user and group IDs using the `PUID` and `PGID` environment variables. This is highly recommended to avoid permission issues when mounting volumes from your host machine. + +To find your current user's ID, run `id -u`. To find your group's ID, run `id -g`. + +Example `docker-compose.yml` snippet: +```yaml +services: + paperless-gpt: + image: icereed/paperless-gpt:latest + environment: + - PUID=1001 + - PGID=1001 + # ... other variables +``` + ## Contributing **Pull requests** and **issues** are welcome! diff --git a/docker-compose.yml b/docker-compose.yml index 0a1b091d..c2778e9a 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -5,5 +5,11 @@ services: dockerfile: Dockerfile ports: - "8080:8080" + environment: + # Set the user and group IDs for the container user. + # This helps avoid permission issues with mounted volumes. + # Find your user's ID with `id -u` and group ID with `id -g`. + - PUID=1000 + - PGID=1000 env_file: - .env diff --git a/entrypoint.sh b/entrypoint.sh new file mode 100755 index 00000000..352c7e5d --- /dev/null +++ b/entrypoint.sh @@ -0,0 +1,28 @@ +#!/bin/sh +set -e + +# Use environment variables PUID/PGID, otherwise default to 1000 +PUID=${PUID:-1000} +PGID=${PGID:-1000} + +# Create group and user +if ! getent group paperless-gpt >/dev/null; then + addgroup -g ${PGID} paperless-gpt +fi + +if ! getent passwd paperless-gpt >/dev/null; then + adduser -D -S -h /home/paperless-gpt -s /sbin/nologin -G paperless-gpt -u ${PUID} paperless-gpt +fi + +# Create necessary directories +mkdir -p /app/prompts /app/config /app/db /home/paperless-gpt + +# Set ownership for app and home directories to handle all file permissions +chown -R paperless-gpt:paperless-gpt /app /home/paperless-gpt + +# Set HOME env var to user's home directory to ensure configs are written there +export HOME=/home/paperless-gpt + +# Drop privileges and execute the main application +echo "Starting application as user paperless-gpt (${PUID}:${PGID})" +exec su-exec paperless-gpt /app/paperless-gpt From a0845913c978051a5853839d65420c77bb537cea Mon Sep 17 00:00:00 2001 From: Henning Dickten Date: Sun, 19 Oct 2025 04:51:12 +0200 Subject: [PATCH 2/2] move to PUID > 10000 and ensure PUID is not root --- README.md | 8 ++++---- docker-compose.yml | 4 ++-- entrypoint.sh | 12 +++++++++--- 3 files changed, 15 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 970f3a34..8e1d443f 100644 --- a/README.md +++ b/README.md @@ -531,8 +531,8 @@ For best results with the enhanced OCR features: | Variable | Description | Required | Default | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------- | -| `PUID` | User ID to run the container as. See [Running as a Non-Root User](#running-as-a-non-root-user). | No | 1000 | -| `PGID` | Group ID to run the container as. See [Running as a Non-Root User](#running-as-a-non-root-user). | No | 1000 | +| `PUID` | User ID to run the container as. See [Running as a Non-Root User](#running-as-a-non-root-user). | No | 10001 | +| `PGID` | Group ID to run the container as. See [Running as a Non-Root User](#running-as-a-non-root-user). | No | 10001 | | `PAPERLESS_BASE_URL` | URL of your paperless-ngx instance (e.g. `http://paperless-ngx:8000`). | Yes | | | `PAPERLESS_API_TOKEN` | API token for paperless-ngx. Generate one in paperless-ngx admin. | Yes | | | `PAPERLESS_PUBLIC_URL` | Public URL for Paperless (if different from `PAPERLESS_BASE_URL`). | No | | @@ -949,8 +949,8 @@ services: paperless-gpt: image: icereed/paperless-gpt:latest environment: - - PUID=1001 - - PGID=1001 + - PUID=10001 + - PGID=10001 # ... other variables ``` diff --git a/docker-compose.yml b/docker-compose.yml index c2778e9a..a0386533 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -9,7 +9,7 @@ services: # Set the user and group IDs for the container user. # This helps avoid permission issues with mounted volumes. # Find your user's ID with `id -u` and group ID with `id -g`. - - PUID=1000 - - PGID=1000 + - PUID=10001 + - PGID=10001 env_file: - .env diff --git a/entrypoint.sh b/entrypoint.sh index 352c7e5d..ceb6417e 100755 --- a/entrypoint.sh +++ b/entrypoint.sh @@ -1,9 +1,15 @@ #!/bin/sh set -e -# Use environment variables PUID/PGID, otherwise default to 1000 -PUID=${PUID:-1000} -PGID=${PGID:-1000} +# Use environment variables PUID/PGID, otherwise default to 10001 +PUID=${PUID:-10001} +PGID=${PGID:-10001} + +# Validate PUID/PGID +if [ "${PUID}" -lt 1 ] || [ "${PGID}" -lt 1 ]; then + echo "ERROR: PUID and PGID must non-root (0) and positive integers (got PUID=${PUID}, PGID=${PGID})" + exit 1 +fi # Create group and user if ! getent group paperless-gpt >/dev/null; then