Use gosu for reliable UID:GID switching

Fix PUID/PGID collision issues by using gosu to run services with exact UID:GID. Changes include:

- Added redis-start.sh and updated app-start.sh to load /etc/environment, determine PUID/PGID, and invoke gosu "$PUID:$PGID" to start Redis and the Next.js app (with verification and fallbacks).
- Updated entrypoint.sh to persist PUID/PGID into /etc/environment, document the gosu approach, and adjust startup messaging.
- Updated supervisord.conf to run the new startup wrappers as root (so they can use gosu) instead of running processes directly as specific users.
- Dockerfile updated to install gosu and copy the redis-start.sh wrapper.
- Documentation updated (deployment/unified.md) describing the PUID collision bug, the root cause, and the gosu-based fix.

This resolves cases where PUID collides with existing system users (e.g., nobody) which previously caused processes to run with the wrong GID and produce EACCES errors.

docker/unified/app-start.sh

@@ -1,22 +1,59 @@
 #!/bin/bash
 # App startup wrapper for unified container
-# Starts Next.js server and initializes services
+# Uses gosu to ensure correct PUID:PGID for file operations
+
+set -e
+
+# Load environment from /etc/environment (set by entrypoint)
+if [ -f /etc/environment ]; then
+    set -a
+    source /etc/environment
+    set +a
+fi
+
+# Get PUID/PGID (default to node user's current IDs if not set)
+PUID=${PUID:-$(id -u node)}
+PGID=${PGID:-$(id -g node)}
 
 echo "[App] Starting Next.js server..."
+echo "[App] Process will run as UID:GID = $PUID:$PGID"
+
 cd /app
 
-# Start server in background
-node server.js &
-SERVER_PID=$!
+# Use gosu to switch to correct UID:GID and start server
+# This bypasses username resolution issues when PUID collides with existing users
+if [ "$(id -u)" = "0" ]; then
+    # Running as root - use gosu to switch to PUID:PGID
+    echo "[App] Switching to UID:GID $PUID:$PGID via gosu..."
 
-echo "[App] Waiting for server to be ready..."
-sleep 5
+    # Start server in background with gosu
+    gosu "$PUID:$PGID" node server.js &
+    SERVER_PID=$!
 
-# Initialize application services (creates default scheduled jobs)
-echo "[App] Initializing application services..."
-curl -f http://localhost:3030/api/init || echo "[App] ⚠️  Warning: Failed to initialize services"
+    echo "[App] Waiting for server to be ready..."
+    sleep 5
 
-echo "[App] Server ready with PID $SERVER_PID"
+    # Initialize application services (creates default scheduled jobs)
+    echo "[App] Initializing application services..."
+    curl -sf http://localhost:3030/api/init || echo "[App] Warning: Failed to initialize services (may already be initialized)"
 
-# Wait for server process
-wait $SERVER_PID
+    echo "[App] Server ready with PID $SERVER_PID (running as $PUID:$PGID)"
+
+    # Verify the process is running with correct UID:GID
+    if [ -f "/proc/$SERVER_PID/status" ]; then
+        ACTUAL_UID=$(grep '^Uid:' /proc/$SERVER_PID/status | awk '{print $2}')
+        ACTUAL_GID=$(grep '^Gid:' /proc/$SERVER_PID/status | awk '{print $2}')
+        echo "[App] Verified process credentials: UID=$ACTUAL_UID GID=$ACTUAL_GID"
+
+        if [ "$ACTUAL_UID" != "$PUID" ] || [ "$ACTUAL_GID" != "$PGID" ]; then
+            echo "[App] WARNING: Process UID:GID ($ACTUAL_UID:$ACTUAL_GID) does not match expected ($PUID:$PGID)"
+        fi
+    fi
+
+    # Wait for server process
+    wait $SERVER_PID
+else
+    # Not running as root - just run directly (fallback)
+    echo "[App] Warning: Not running as root, cannot use gosu. Running as current user."
+    exec node server.js
+fi

docker/unified/entrypoint.sh

@@ -4,12 +4,16 @@ set -e
 echo "🚀 ReadMeABook Unified Container Starting..."
 
 # ============================================================================
-# PUID/PGID USER REMAPPING (Hybrid approach)
+# PUID/PGID USER REMAPPING (Hybrid approach with gosu)
 # ============================================================================
 # Hybrid approach to support user file ownership while maintaining PostgreSQL compatibility:
 # - postgres user: Keep UID 103 (required by PostgreSQL), remap GID → PGID
-# - redis user:    Remap UID → PUID, GID → PGID
-# - node user:     Remap UID → PUID, GID → PGID
+# - redis user:    Remap UID → PUID, GID → PGID (also uses gosu at runtime)
+# - node user:     Remap UID → PUID, GID → PGID (also uses gosu at runtime)
+#
+# NOTE: We use gosu in app-start.sh and redis-start.sh to ensure the process
+# actually runs with the correct UID:GID. This fixes issues where PUID collides
+# with existing system users (e.g., PUID=65534 collides with 'nobody').
 #
 # Result:
 # - PostgreSQL data (103:PGID) - postgres user with shared group
@@ -309,7 +313,8 @@ export NODE_ENV="production"
 export PORT="3030"
 export HOSTNAME="0.0.0.0"
 
-# Persist environment variables for supervisord
+# Persist environment variables for supervisord and child processes
+# PUID/PGID are critical for gosu-based user switching in app-start.sh and redis-start.sh
 cat > /etc/environment <<EOF
 DATABASE_URL=$DATABASE_URL
 REDIS_URL=$REDIS_URL
@@ -322,6 +327,8 @@ LOG_LEVEL=$LOG_LEVEL
 NODE_ENV=$NODE_ENV
 PORT=$PORT
 HOSTNAME=$HOSTNAME
+PUID=${PUID:-}
+PGID=${PGID:-}
 EOF
 
 echo "✅ Environment configured"
@@ -353,9 +360,14 @@ if [ "$POSTGRES_PASSWORD" = "$(generate_secret)" ]; then
 fi
 echo ""
 echo "📊 Services starting:"
-echo "   - PostgreSQL (internal)"
-echo "   - Redis (internal)"
-echo "   - Next.js App (port 3030)"
+echo "   - PostgreSQL (internal, user=postgres)"
+echo "   - Redis (internal, UID:GID=${PUID:-102}:${PGID:-102})"
+echo "   - Next.js App (port 3030, UID:GID=${PUID:-1000}:${PGID:-1000})"
+if [ -n "$PUID" ] && [ -n "$PGID" ]; then
+    echo ""
+    echo "🔐 Using gosu for reliable UID:GID switching"
+    echo "   App and Redis will run as $PUID:$PGID"
+fi
 echo "============================================"
 echo ""
 

docker/unified/redis-start.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Redis startup wrapper for unified container
+# Uses gosu to ensure correct PUID:PGID for file operations
+
+set -e
+
+# Load environment from /etc/environment (set by entrypoint)
+if [ -f /etc/environment ]; then
+    set -a
+    source /etc/environment
+    set +a
+fi
+
+# Get PUID/PGID (default to redis user's current IDs if not set)
+PUID=${PUID:-$(id -u redis)}
+PGID=${PGID:-$(id -g redis)}
+
+echo "[Redis] Starting Redis server..."
+echo "[Redis] Process will run as UID:GID = $PUID:$PGID"
+
+# Use gosu to switch to correct UID:GID and start redis
+# This bypasses username resolution issues when PUID collides with existing users
+if [ "$(id -u)" = "0" ]; then
+    # Running as root - use gosu to switch to PUID:PGID
+    echo "[Redis] Switching to UID:GID $PUID:$PGID via gosu..."
+    exec gosu "$PUID:$PGID" /usr/bin/redis-server --appendonly yes --dir /var/lib/redis --bind 127.0.0.1 --port 6379
+else
+    # Not running as root - just run directly (fallback)
+    echo "[Redis] Warning: Not running as root, cannot use gosu. Running as current user."
+    exec /usr/bin/redis-server --appendonly yes --dir /var/lib/redis --bind 127.0.0.1 --port 6379
+fi

docker/unified/supervisord.conf

@@ -20,8 +20,8 @@ stdout_events_enabled=true
 stderr_events_enabled=true
 
 [program:redis]
-command=/usr/bin/redis-server --appendonly yes --dir /var/lib/redis --bind 127.0.0.1 --port 6379
-user=redis
+command=/app/redis-start.sh
+user=root
 autostart=true
 autorestart=true
 priority=20
@@ -35,7 +35,7 @@ stderr_events_enabled=true
 [program:app]
 command=/app/app-start.sh
 directory=/app
-user=node
+user=root
 autostart=true
 autorestart=true
 priority=30