From f7fe1f30725dccf943fef75684da8b387167f0e3 Mon Sep 17 00:00:00 2001
From: itsvrk <brian@itsvrk.com>
Date: Thu, 22 Jan 2026 12:12:41 +1100
Subject: [PATCH] fix: allow setting of PUID and PGID to prevent permission
 issues when using NFS mounts or shared volumes

---
 README.md            | 20 ++++++++++++++++++++
 docker/Dockerfile    |  7 ++++++-
 docker/entrypoint.sh | 41 +++++++++++++++++++++++++++++++++++++++++
 3 files changed, 67 insertions(+), 1 deletion(-)
 create mode 100644 docker/entrypoint.sh

diff --git a/README.md b/README.md
index bb3ba54..c7036ef 100644
--- a/README.md
+++ b/README.md
@@ -112,14 +112,34 @@ docker pull rustmailer/bichon:latest
 # Create data directory
 mkdir -p ./bichon-data
 
+# Optional: Set PUID and PGID to match your host user for proper file permissions
+# Find your user ID with: id $USER
+# This prevents permission issues when using NFS mounts or shared volumes
+
 # Run container
 docker run -d \
   --name bichon \
   -p 15630:15630 \
   -v $(pwd)/bichon-data:/data \
+  -e PUID=1000 \
+  -e PGID=1000 \
   -e BICHON_LOG_LEVEL=info \
   -e BICHON_ROOT_DIR=/data \
   rustmailer/bichon:latest
+
+# Optional: For custom storage configuration with separate volumes
+docker run -d \
+  --name bichon \
+  -p 15630:15630 \
+  -v $(pwd)/bichon-data:/data \
+  -v $(pwd)/envelope:/envelope \
+  -v $(pwd)/eml:/eml \
+  -e PUID=1000 \
+  -e PGID=1000 \
+  -e BICHON_ROOT_DIR=/data \
+  -e BICHON_INDEX_DIR=/envelope \
+  -e BICHON_DATA_DIR=/eml \
+  rustmailer/bichon:latest
 ```
 
 ## CORS Configuration (Important for Browser Access)
diff --git a/docker/Dockerfile b/docker/Dockerfile
index a135d1b..e684957 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -17,6 +17,10 @@ COPY ${TARGETARCH}/LICENSE /opt/bichon/
 # Set proper permissions
 RUN chmod +x /opt/bichon/bichon
 
+# Copy and setup entrypoint script for PUID/PGID support
+COPY docker/entrypoint.sh /usr/local/bin/entrypoint.sh
+RUN chmod +x /usr/local/bin/entrypoint.sh
+
 # Install ca-certificates to ensure HTTPS certificate verification works correctly
 RUN apt update && apt install -y ca-certificates curl && rm -rf /var/lib/apt/lists/*
 # Create data directory
@@ -31,5 +35,6 @@ WORKDIR /data
 HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
   CMD curl -fs http://localhost:15630/api/status || exit 1
 
-# Entrypoint remains the binary
+# Entrypoint with PUID/PGID support
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
 CMD ["/opt/bichon/bichon"]
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
new file mode 100644
index 0000000..4efd9c3
--- /dev/null
+++ b/docker/entrypoint.sh
@@ -0,0 +1,41 @@
+#!/bin/bash
+
+# Entrypoint script for Bichon Docker container
+# Handles PUID/PGID environment variables for proper user permissions
+
+set -e
+
+# Function to create user and switch to it
+switch_user() {
+    local puid="$1"
+    local pgid="$2"
+
+    # Create group if it doesn't exist
+    if ! getent group bichon >/dev/null 2>&1; then
+        groupadd -g "$pgid" bichon
+    fi
+
+    # Create user if it doesn't exist
+    if ! getent passwd bichon >/dev/null 2>&1; then
+        useradd -u "$puid" -g "$pgid" -s /bin/bash -d /data bichon
+    fi
+
+    # Change ownership of directories that the process needs to write to
+    chown -R "$puid:$pgid" /data
+    chown -R "$puid:$pgid" /opt/bichon
+    # Handle mounted storage directories if they exist
+    [ -d /envelope ] && chown -R "$puid:$pgid" /envelope
+    [ -d /eml ] && chown -R "$puid:$pgid" /eml
+
+    # Switch to the user and execute the command
+    exec runuser -u bichon -- "$@"
+}
+
+# Check if PUID and PGID are set
+if [ -n "$PUID" ] && [ -n "$PGID" ]; then
+    echo "Switching to user with PUID=$PUID, PGID=$PGID"
+    switch_user "$PUID" "$PGID" "$@"
+else
+    echo "No PUID/PGID specified, running as root"
+    exec "$@"
+fi
\ No newline at end of file