feat: improve UID/GID configuration and troubleshooting documentation

- Updated docker-compose example to clarify UID/GID settings for better compatibility with host systems. - Added a new troubleshooting guide to address common permission issues related to bind mounts. - Enhanced existing documentation to emphasize the importance of matching host UID/GID with Palmr's defaults. - Introduced a new troubleshooting section in the documentation to assist users in resolving permission denied errors.
2025-11-02 21:13:17 +00:00 · 2025-06-25 16:48:31 -03:00
parent ea68e771a8
commit 6fbf9af388
5 changed files with 597 additions and 69 deletions
--- a/apps/docs/content/docs/3.0-beta/meta.json
+++ b/apps/docs/content/docs/3.0-beta/meta.json
@@ -18,6 +18,7 @@
    "reverse-proxy-configuration",
    "password-reset-without-smtp",
    "oidc-authentication",
+    "troubleshooting",
    "---Developers---",
    "architecture",
    "github-architecture",
--- a/apps/docs/content/docs/3.0-beta/quick-start.mdx
+++ b/apps/docs/content/docs/3.0-beta/quick-start.mdx
@@ -36,7 +36,7 @@ Palmr. supports two storage approaches for persistent data:
 - ✅ **Direct Access**: Files stored in local directory you specify
 - ✅ **Transparent Storage**: Direct filesystem access from host
 - ✅ **Custom Backup**: Use existing file system backup solutions
- ⚠️ **Permission Considerations**: May require user/group configuration
+- ⚠️ **Permission Considerations**: **Common Issue** - Requires UID/GID configuration (see troubleshooting below)

 ---

@@ -93,9 +93,8 @@ services:
      - ENABLE_S3=false
      - ENCRYPTION_KEY=change-this-key-in-production-min-32-chars # CHANGE THIS KEY FOR SECURITY
      # - SECURE_SITE=false # Set to true if you are using a reverse proxy
-      # Optional: Set custom UID/GID for file permissions
-      # - PALMR_UID=1000
-      # - PALMR_GID=1000
+      - PALMR_UID=1000 # Set to your user ID (run 'id' to find it)
+      - PALMR_GID=1000 # Set to your group ID (run 'id' to find it)
    ports:
      - "5487:5487" # Web port
      - "3333:3333" # API port (OPTIONAL EXPOSED - ONLY IF YOU WANT TO ACCESS THE API DIRECTLY)
@@ -111,7 +110,32 @@ services:
 docker-compose up -d
 ```

-> **Permission Configuration**: If you encounter permission issues with bind mounts (common on NAS systems), see our [UID/GID Configuration](/docs/3.0-beta/uid-gid-configuration) guide for automatic permission handling.
+> **⚠️ Common Issue**: If you get "permission denied" errors, it's because Palmr uses UID 1001 by default, but most Linux systems use UID 1000. The configuration above already includes the fix (`PALMR_UID=1000`). See our [UID/GID Configuration](/docs/3.0-beta/uid-gid-configuration) guide for detailed troubleshooting.
+
+### Troubleshooting Bind Mount Permissions
+
+If you encounter permission errors:
+
+```bash
+# 1. Check your UID/GID
+id
+# Example output: uid=1000(user) gid=1000(group)
+
+# 2. Make sure these match your docker-compose.yaml:
+# - PALMR_UID=1000  # ← Your UID here
+# - PALMR_GID=1000  # ← Your GID here
+
+# 3. Restart the container
+docker-compose down && docker-compose up -d
+```
+
+**Alternative fix** (if you prefer not to use environment variables):
+
+```bash
+# Create directories with Palmr's default ownership
+mkdir -p data
+chown -R 1001:1001 data
+```

 ---

--- a/apps/docs/content/docs/3.0-beta/troubleshooting.mdx
+++ b/apps/docs/content/docs/3.0-beta/troubleshooting.mdx
@@ -0,0 +1,377 @@
+---
+title: Troubleshooting
+icon: "Bug"
+---
+
+Common issues and solutions for Palmr. deployment and usage.
+
+## 🚨 Permission Denied Errors
+
+**Most common issue**: Permission denied when uploading files or accessing data directories.
+
+### Quick Diagnosis
+
+```bash
+# Check if this is a permission issue
+docker-compose logs palmr | grep -i "permission\|denied\|eacces"
+
+# Common error messages:
+# EACCES: permission denied, open '/app/server/uploads/file.txt'
+# Error: EACCES: permission denied, mkdir '/app/server/temp-chunks'
+```
+
+### The Root Cause
+
+**Palmr. defaults**: UID 1001, GID 1001  
+**Linux standard**: UID 1000, GID 1000
+
+When using bind mounts, your host directories are owned by UID 1000, but Palmr. runs as UID 1001.
+
+### Solution 1: Environment Variables (Recommended)
+
+Set Palmr. to use your host system's UID/GID:
+
+```bash
+# Find your UID/GID
+id
+# Output: uid=1000(user) gid=1000(group) groups=1000(group),27(sudo)
+```
+
+Add to your `docker-compose.yaml`:
+
+```yaml
+services:
+  palmr:
+    environment:
+      - PALMR_UID=1000 # Your UID
+      - PALMR_GID=1000 # Your GID
+    # ... rest of config
+```
+
+Restart the container:
+
+```bash
+docker-compose down && docker-compose up -d
+```
+
+### Solution 2: Change Host Directory Ownership
+
+If you prefer to keep Palmr's defaults:
+
+```bash
+# For single data directory
+chown -R 1001:1001 ./data
+
+# For separate upload/temp directories
+mkdir -p uploads temp-chunks
+chown -R 1001:1001 uploads temp-chunks
+```
+
+### Solution 3: Docker Volume (Avoid the Issue)
+
+Use Docker named volumes instead of bind mounts:
+
+```yaml
+volumes:
+  - palmr_data:/app/server  # Named volume (no permission issues)
+  # Instead of:
+  # - ./data:/app/server    # Bind mount (permission issues)
+
+volumes:
+  palmr_data:
+```
+
+---
+
+## 🐳 Container Issues
+
+### Container Won't Start
+
+**Check logs first:**
+
+```bash
+docker-compose logs palmr
+```
+
+**Common issues:**
+
+1. **Port already in use**
+
+   ```bash
+   # Check what's using port 5487
+   sudo lsof -i :5487
+
+   # Or change port in docker-compose.yaml
+   ports:
+     - "5488:5487"  # Use different host port
+   ```
+
+2. **Invalid encryption key**
+
+   ```bash
+   # Error: Encryption key must be at least 32 characters
+   # Fix: Update ENCRYPTION_KEY in docker-compose.yaml
+   environment:
+     - ENCRYPTION_KEY=your-very-long-secure-key-at-least-32-characters
+   ```
+
+3. **Missing environment variables**
+   ```bash
+   # Check required variables are set
+   docker exec palmr env | grep -E "ENCRYPTION_KEY|DATABASE_URL"
+   ```
+
+### Container Starts But App Doesn't Load
+
+```bash
+# Check if services are running inside container
+docker exec palmr ps aux
+
+# Check if ports are bound correctly
+docker port palmr
+
+# Test API directly
+curl http://localhost:3333/health
+```
+
+---
+
+## 📁 File Upload Issues
+
+### Files Not Uploading
+
+1. **Check disk space:**
+
+   ```bash
+   df -h
+   # Ensure you have enough space in upload directory
+   ```
+
+2. **Check file permissions in container:**
+
+   ```bash
+   docker exec palmr ls -la /app/server/uploads/
+   # Should show ownership by palmr user
+   ```
+
+3. **Check upload limits:**
+   - Default max file size is configurable
+   - Check browser network tab for 413 errors
+
+### Files Upload But Can't Be Downloaded
+
+```bash
+# Check file exists and is readable
+docker exec palmr ls -la /app/server/uploads/
+
+# Check file ownership
+docker exec palmr stat /app/server/uploads/your-file.txt
+```
+
+---
+
+## 🔑 Authentication Issues
+
+### Can't Login to Admin Account
+
+1. **Reset admin password:**
+
+   ```bash
+   # Using the built-in reset script
+   docker exec -it palmr /app/reset-password.sh
+   ```
+
+2. **Check database permissions:**
+   ```bash
+   docker exec palmr ls -la /app/server/prisma/
+   # palmr.db should be writable by palmr user
+   ```
+
+### OIDC Authentication Not Working
+
+See our [OIDC Configuration Guide](/docs/3.0-beta/oidc-authentication) for detailed setup.
+
+---
+
+## 🌐 Network Issues
+
+### Can't Access Web Interface
+
+1. **From localhost:**
+
+   ```bash
+   # Test if container is responding
+   curl http://localhost:5487
+
+   # Check if port is bound
+   docker port palmr 5487
+   ```
+
+2. **From external network:**
+
+   ```bash
+   # Check firewall
+   sudo ufw status
+
+   # Test from external IP
+   curl http://YOUR_SERVER_IP:5487
+   ```
+
+### API Not Accessible
+
+```bash
+# Check if API port is exposed
+docker port palmr 3333
+
+# Test API health
+curl http://localhost:3333/health
+
+# Check API documentation
+curl http://localhost:3333/docs
+```
+
+---
+
+## 💾 Database Issues
+
+### Database Connection Errors
+
+```bash
+# Check database file exists and is writable
+docker exec palmr ls -la /app/server/prisma/palmr.db
+
+# Check database logs
+docker-compose logs palmr | grep -i database
+
+# Verify Prisma schema
+docker exec palmr npx prisma db push --schema=./prisma/schema.prisma
+```
+
+### Database Corruption
+
+```bash
+# Stop container
+docker-compose down
+
+# Backup existing database
+cp ./data/prisma/palmr.db ./data/prisma/palmr.db.backup
+
+# Let Palmr recreate database on startup
+rm ./data/prisma/palmr.db
+
+# Start container (will recreate database)
+docker-compose up -d
+```
+
+---
+
+## 🚀 Performance Issues
+
+### Slow File Uploads
+
+1. **Check available disk space:**
+
+   ```bash
+   df -h
+   ```
+
+2. **Monitor container resources:**
+
+   ```bash
+   docker stats palmr
+   ```
+
+3. **Check temp directory permissions:**
+   ```bash
+   docker exec palmr ls -la /app/server/temp-chunks/
+   ```
+
+### High Memory Usage
+
+```bash
+# Check container memory usage
+docker stats palmr
+
+# Check Node.js memory usage
+docker exec palmr ps aux | grep node
+```
+
+---
+
+## 🔍 Diagnostic Commands
+
+### Complete Health Check
+
+```bash
+#!/bin/bash
+echo "=== Palmr. Health Check ==="
+
+echo "1. Container Status:"
+docker ps | grep palmr
+
+echo "2. Container Logs (last 20 lines):"
+docker-compose logs --tail=20 palmr
+
+echo "3. Port Status:"
+docker port palmr
+
+echo "4. File Permissions:"
+docker exec palmr ls -la /app/server/
+
+echo "5. Environment Variables:"
+docker exec palmr env | grep -E "PALMR_|ENCRYPTION_|DATABASE_"
+
+echo "6. API Health:"
+curl -s http://localhost:3333/health || echo "API not accessible"
+
+echo "7. Web Interface:"
+curl -s -o /dev/null -w "%{http_code}" http://localhost:5487 || echo "Web interface not accessible"
+
+echo "8. Disk Space:"
+df -h
+
+echo "=== End Health Check ==="
+```
+
+### Log Analysis
+
+```bash
+# Check for common errors
+docker-compose logs palmr 2>&1 | grep -E "error|Error|ERROR|failed|Failed|FAILED"
+
+# Check permission issues
+docker-compose logs palmr 2>&1 | grep -E "permission|denied|EACCES"
+
+# Check startup sequence
+docker-compose logs palmr 2>&1 | grep -E "🌴|🔧|🚀|✅"
+```
+
+---
+
+## 📞 Getting Help
+
+If none of these solutions work:
+
+1. **Gather diagnostic information:**
+
+   ```bash
+   # Run the complete health check above
+   # Save the output to a file
+   ```
+
+2. **Check our documentation:**
+
+   - [UID/GID Configuration](/docs/3.0-beta/uid-gid-configuration)
+   - [Quick Start Guide](/docs/3.0-beta/quick-start)
+   - [API Reference](/docs/3.0-beta/api)
+
+3. **Open an issue on GitHub:**
+
+   - Include your `docker-compose.yaml`
+   - Include relevant log output
+   - Describe your system (OS, Docker version, etc.)
+   - [GitHub Issues](https://github.com/kyantech/Palmr/issues)
+
+4. **Check existing issues:**
+   - Search [closed issues](https://github.com/kyantech/Palmr/issues?q=is%3Aissue+is%3Aclosed) for similar problems
+   - Look for recent [discussions](https://github.com/kyantech/Palmr/discussions)
--- a/apps/docs/content/docs/3.0-beta/uid-gid-configuration.mdx
+++ b/apps/docs/content/docs/3.0-beta/uid-gid-configuration.mdx
@@ -9,16 +9,63 @@ Configure user and group permissions for seamless bind mount compatibility acros

 Palmr. supports runtime UID/GID configuration to resolve permission conflicts when using bind mounts. This eliminates the need for manual permission management on your host system.

-**Default Configuration**: UID 1001, GID 1001
+**⚠️ Important**: Palmr uses **UID 1001, GID 1001** by default, which is different from the standard Linux convention of **UID 1000, GID 1000**. This is the most common cause of permission issues with bind mounts.

-## When to Configure
+## The Permission Problem

-UID/GID configuration is recommended when:
+### Why This Happens

- Using bind mounts with different host user permissions
- Deploying on NAS systems (Synology, QNAP, etc.)
- Encountering "permission denied" errors
- Host system uses different default UID/GID values
+- **Palmr Default**: UID 1001, GID 1001 (container)
+- **Linux Standard**: UID 1000, GID 1000 (most host systems)
+- **Result**: Container can't write to host directories
+
+### Common Error Scenarios
+
+```bash
+# When you see errors like:
+EACCES: permission denied, open '/app/server/uploads/file.txt'
+```
+
+```bash
+# Or when checking permissions:
+$ ls -la uploads/
+drwxr-xr-x 2 user user 4096 Jan 15 10:00 uploads/
+# Container tries to write as UID 1001, but directory is owned by UID 1000
+```
+
+## Quick Fix
+
+### Option 1: Set Palmr to Use Standard UID/GID (Recommended)
+
+Add these environment variables to your `docker-compose.yaml`:
+
+```yaml
+services:
+  palmr:
+    image: kyantech/palmr:latest
+    container_name: palmr
+    environment:
+      - ENABLE_S3=false
+      - ENCRYPTION_KEY=your-secure-key-min-32-chars
+      - PALMR_UID=1000
+      - PALMR_GID=1000
+    ports:
+      - "5487:5487"
+    volumes:
+      - ./uploads:/app/server/uploads:rw
+      - ./temp-chunks:/app/server/temp-chunks:rw
+    restart: unless-stopped
+```
+
+### Option 2: Change Host Directory Permissions
+
+If you prefer to keep Palmr's defaults:
+
+```bash
+# Create directories with correct ownership
+mkdir -p uploads temp-chunks
+chown -R 1001:1001 uploads temp-chunks
+```

 ## Environment Variables

@@ -31,7 +78,7 @@ Configure permissions using these optional environment variables:

 ---

-## Finding Host UID/GID
+## Finding Your Host UID/GID

 Determine your host system's user and group IDs:

@@ -43,13 +90,13 @@ id
 uid=1000(user) gid=1000(group) groups=1000(group),27(sudo)
 ```

-Use the `uid` and `gid` values for your configuration.
+Use the `uid` and `gid` values for your `PALMR_UID` and `PALMR_GID` configuration.

 ---

 ## Configuration Examples

-### Standard Linux System
+### Standard Linux System (Most Common)

 ```yaml
 services:
@@ -108,6 +155,103 @@ services:

 ---

+## Troubleshooting
+
+### Common Permission Errors
+
+**Error**: `EACCES: permission denied`
+
+```bash
+# 1. Check your current UID/GID
+id
+
+# 2. Check directory ownership
+ls -la uploads/ temp-chunks/
+
+# 3. Fix via environment variables (preferred)
+# Add to docker-compose.yaml:
+# - PALMR_UID=1000
+# - PALMR_GID=1000
+
+# 4. Or fix via chown (alternative)
+chown -R 1001:1001 uploads temp-chunks
+```
+
+**Error**: Container starts but files aren't accessible
+
+```bash
+# Check container's UID/GID configuration
+docker-compose logs palmr | grep -E "🔧|Runtime UID/GID"
+
+# Check file ownership inside container
+docker exec palmr ls -la /app/server/
+```
+
+### Verification Commands
+
+Verify UID/GID settings are applied correctly:
+
+```bash
+# View startup logs for UID/GID configuration
+docker-compose logs palmr | head -20
+
+# Check file ownership in container
+docker exec palmr ls -la /app/server/
+
+# Verify process is running with correct UID/GID
+docker exec palmr ps aux | grep node
+
+# Check environment variables
+docker exec palmr env | grep PALMR
+```
+
+### Advanced Troubleshooting
+
+**NAS-specific debugging:**
+
+```bash
+# Synology - Check mount point ownership
+ls -la /volume1/docker/palmr/
+
+# QNAP - Check mount point ownership
+ls -la /share/Container/palmr/
+
+# Check NAS user configuration
+cat /etc/passwd | grep -v nobody
+```
+
+**Docker bind mount issues:**
+
+```bash
+# Check if directories exist and are writable
+test -w uploads && echo "uploads writable" || echo "uploads NOT writable"
+test -w temp-chunks && echo "temp-chunks writable" || echo "temp-chunks NOT writable"
+
+# Create directories with correct permissions
+mkdir -p uploads temp-chunks
+sudo chown -R $(id -u):$(id -g) uploads temp-chunks
+```
+
+---
+
+## When to Configure
+
+UID/GID configuration is **required** when:
+
+- ✅ Using bind mounts (most common case)
+- ✅ Encountering "permission denied" errors
+- ✅ Deploying on NAS systems (Synology, QNAP, etc.)
+- ✅ Host system uses different default UID/GID values
+- ✅ Running multiple containers that need to share files
+
+UID/GID configuration is **optional** when:
+
+- ❌ Using Docker named volumes (Docker manages permissions)
+- ❌ Not using bind mounts
+- ❌ No permission errors occurring
+
+---
+
 ## Migration Guide

 ### Existing Installations
@@ -124,65 +268,33 @@ To add UID/GID configuration to running installations:

   ```bash
   cp -r ./data ./data-backup
+   # or
+   cp -r ./uploads ./uploads-backup
+   cp -r ./temp-chunks ./temp-chunks-backup
   ```

-3. **Update configuration**
-   Add UID/GID variables to your `docker-compose.yaml`
+3. **Check your UID/GID**

-4. **Restart with new configuration**
+   ```bash
+   id
+   ```
+
+4. **Update configuration**
+   Add UID/GID variables to your `docker-compose.yaml`:
+
+   ```yaml
+   environment:
+     - PALMR_UID=1000
+     - PALMR_GID=1000
+   ```
+
+5. **Restart with new configuration**
   ```bash
   docker-compose up -d
   ```

 ---

-## Verification
-
-### Check Configuration
-
-Verify UID/GID settings are applied correctly:
-
-```bash
-# View startup logs
-docker-compose logs palmr | head -20
-
-# Check file ownership
-docker exec palmr ls -la /app/server/
-
-# Verify process UID/GID
-docker exec palmr ps aux | grep node
-```
-
-### Troubleshooting
-
-**Permission issues persist:**
-
-```bash
-# Check environment variables
-docker exec palmr env | grep PALMR
-
-# Verify file ownership
-docker exec palmr stat /app/server/prisma/palmr.db
-
-# Review configuration logs
-docker-compose logs palmr | grep -E "🔧|🔐|🔽"
-```
-
-**NAS-specific debugging:**
-
-```bash
-# Synology - Check mount point ownership
-ls -la /volume1/docker/palmr/
-
-# QNAP - Check mount point ownership
-ls -la /share/Container/palmr/
-
-# Check NAS user configuration
-cat /etc/passwd | grep -v nobody
-```
-
---
-
 ## Implementation Details

 The UID/GID configuration process:
@@ -219,4 +331,17 @@ Runtime environment variables override build-time defaults.
 - **Backward Compatible** - Existing deployments continue without modification
 - **Performance Optimized** - Lightweight implementation using `su-exec`

-For permission issues with bind mounts, add the appropriate `PALMR_UID` and `PALMR_GID` environment variables to resolve conflicts automatically.
+## Summary
+
+For most users experiencing permission issues with bind mounts:
+
+1. **Find your UID/GID**: Run `id` command
+2. **Add to docker-compose.yaml**:
+   ```yaml
+   environment:
+     - PALMR_UID=1000
+     - PALMR_GID=1000
+   ```
+3. **Restart**: `docker-compose down && docker-compose up -d`
+
+This resolves the mismatch between Palmr's default UID 1001 and the standard Linux UID 1000.
--- a/docker-compose-bind-mount-example.yaml
+++ b/docker-compose-bind-mount-example.yaml
@@ -5,9 +5,10 @@ services:
    environment:
      - ENABLE_S3=false
      - ENCRYPTION_KEY=change-this-key-in-production-min-32-chars # CHANGE THIS KEY FOR SECURITY
-      # Optional: Set custom UID/GID for file permissions
-      # - PALMR_UID=1000
-      # - PALMR_GID=1000
+      # IMPORTANT: Set these to match your host user/group (run 'id' command to find yours)
+      # Palmr defaults to UID 1001, but most Linux systems use UID 1000
+      - PALMR_UID=1000 # Replace with your UID (from 'id' command)
+      - PALMR_GID=1000 # Replace with your GID (from 'id' command)
    ports:
      - "5487:5487" # Web port
      - "3333:3333" # API port (OPTIONAL EXPOSED - ONLY IF YOU WANT TO ACCESS THE API DIRECTLY)