Palmr.

Troubleshooting

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

# 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-uploads'

The Root Cause

Palmr. defaults: UID 1001, GID 1001
Linux standard: UID 1000, GID 1000

When using bind mounts, your host directories may have different ownership than Palmr's default UID/GID.

Set Palmr. to use your host system's UID/GID:

# Find your UID/GID
id
# Output: uid=1000(user) gid=1000(group) groups=1000(group),27(sudo)

Add to your docker-compose.yaml:

services:
  palmr:
    environment:
      - PALMR_UID=1000 # Your UID
      - PALMR_GID=1000 # Your GID
    # ... rest of config

Restart the container:

docker-compose down && docker-compose up -d

Solution 2: Change Host Directory Ownership

If you prefer to keep Palmr's defaults:

# For single data directory
chown -R 1001:1001 ./data
 
# For separate upload/temp directories
mkdir -p uploads temp-uploads
chown -R 1001:1001 uploads temp-uploads

Solution 3: Docker Volume (Avoid the Issue)

Use Docker named volumes instead of bind mounts:

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:

docker-compose logs palmr

Common issues:

  1. Port already in use

    # 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

    # Error: Encryption key must be at least 32 characters (only if encryption is enabled)
# Fix: Either disable encryption or provide a valid key
environment:
  - DISABLE_FILESYSTEM_ENCRYPTION=true  # Disable encryption (default)
  # OR enable encryption with:
  # - DISABLE_FILESYSTEM_ENCRYPTION=false
  # - ENCRYPTION_KEY=your-very-long-secure-key-at-least-32-characters

  3. Missing environment variables

    # Check variables are set (encryption is optional)
docker exec palmr env | grep -E "DISABLE_FILESYSTEM_ENCRYPTION|ENCRYPTION_KEY|DATABASE_URL"

Container Starts But App Doesn't Load

# 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:

    df -h
# Ensure you have enough space in upload directory

  2. Check file permissions in container:

    docker exec palmr ls -la /app/server/uploads/
# Should show ownership by palmr user (UID 1001)

  3. Check upload limits:

    • Default max file size is configurable
    • Check browser network tab for 413 errors

Files Upload But Can't Be Downloaded

# 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:

    # Using the built-in reset script
docker exec -it palmr /app/palmr-app/reset-password.sh

  2. Check database permissions:

    docker exec palmr ls -la /app/server/prisma/
# palmr.db should be writable by palmr user (UID 1001)

OIDC Authentication Not Working

See our OIDC Configuration Guide for detailed setup.

🌐 Network Issues

Can't Access Web Interface

  1. From localhost:

    # Test if container is responding
curl http://localhost:5487
 
# Check if port is bound
docker port palmr 5487

  2. From external network:

    # Check firewall
sudo ufw status
 
# Test from external IP
curl http://YOUR_SERVER_IP:5487

API Not Accessible

# 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

# 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 (run from palmr-app directory)
docker exec palmr sh -c "cd /app/palmr-app && npx prisma db push"

Database Corruption

# 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:

    df -h

  2. Monitor container resources:

    docker stats palmr

  3. Check temp directory permissions:

    docker exec palmr ls -la /app/server/temp-uploads/

High Memory Usage

# Check container memory usage
docker stats palmr
 
# Check Node.js memory usage
docker exec palmr ps aux | grep node

🔍 Diagnostic Commands

Complete Health Check

#!/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. Application Files:"
docker exec palmr ls -la /app/palmr-app/
 
echo "6. Environment Variables:"
docker exec palmr env | grep -E "PALMR_|DISABLE_FILESYSTEM_ENCRYPTION|ENCRYPTION_|DATABASE_"
 
echo "7. API Health:"
curl -s http://localhost:3333/health || echo "API not accessible"
 
echo "8. Web Interface:"
curl -s -o /dev/null -w "%{http_code}" http://localhost:5487 || echo "Web interface not accessible"
 
echo "9. Disk Space:"
df -h
 
echo "=== End Health Check ==="

Log Analysis

# 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:

    # Run the complete health check above
# Save the output to a file

  2. Check our documentation:

  3. Open an issue on GitHub:

    • Include your docker-compose.yaml
    • Include relevant log output
    • Describe your system (OS, Docker version, etc.)
    • GitHub Issues

  4. Check existing issues:

On this page