feat: Run Docker container as non-root user

Dockerfile

@@ -88,19 +88,24 @@ 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/
 
 # 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"]

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       | 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       |                            |
@@ -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=10001
+      - PGID=10001
+      # ... other variables
+```
+
 ## Contributing
 
 **Pull requests** and **issues** are welcome!

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=10001
+      - PGID=10001
     env_file:
       - .env

entrypoint.sh

@@ -0,0 +1,34 @@
+#!/bin/sh
+set -e
+
+# 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
+    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