soulsync/DOCKER_PERMISSIONS.md

Docker Permissions Guide

Understanding PUID/PGID/UMASK

SoulSync supports dynamic user/group ID configuration to ensure files are created with the correct ownership, especially important when sharing files with other containers like Lidarr, Sonarr, or Plex.

What are PUID and PGID?

• PUID (Process User ID): The numeric user ID the container runs as
• PGID (Process Group ID): The numeric group ID the container runs as
• UMASK: Controls default permissions for newly created files/directories

Quick Start

Finding Your IDs

On your host system, run:

id your_username

Example output:

uid=1000(myuser) gid=1000(myuser) groups=1000(myuser),999(docker)

Your PUID is 1000 and PGID is 1000.

Matching Lidarr/Sonarr/Plex

If you're using SoulSync with Lidarr, check Lidarr's docker-compose to see what PUID/PGID it uses:

# Your Lidarr container
services:
  lidarr:
    environment:
      - PUID=99
      - PGID=100

Then set SoulSync to match:

# Your SoulSync container
services:
  soulsync:
    environment:
      - PUID=99      # Match Lidarr
      - PGID=100     # Match Lidarr
      - UMASK=002    # Allows group write permissions

Common Scenarios

Scenario 1: Sharing with Lidarr (Unraid)

Problem: Lidarr can't import files downloaded by SoulSync

Solution: Match the PUID/PGID

services:
  soulsync:
    environment:
      - PUID=99      # Common Unraid user
      - PGID=100     # Common Unraid group
      - UMASK=002

Scenario 2: Single User System

Problem: Default 1000:1000 works but want to match your user

Solution: Use your user's IDs (run id command)

services:
  soulsync:
    environment:
      - PUID=1000    # Your user ID
      - PGID=1000    # Your group ID
      - UMASK=022

Scenario 3: Multiple Containers Sharing Files

Problem: Multiple containers (Plex, Lidarr, SoulSync) need access to same files

Solution: All containers should use same PUID/PGID

services:
  plex:
    environment:
      - PUID=1000
      - PGID=1000

  lidarr:
    environment:
      - PUID=1000
      - PGID=1000

  soulsync:
    environment:
      - PUID=1000
      - PGID=1000
      - UMASK=002    # Allows all containers to write

UMASK Values Explained

UMASK controls default permissions:

• 022: Files: 644 (rw-r--r--), Directories: 755 (rwxr-xr-x)

  • Owner: read/write
  • Group: read only
  • Others: read only
  • Use when: Only you need to modify files

• 002: Files: 664 (rw-rw-r--), Directories: 775 (rwxrwxr-x)

  • Owner: read/write
  • Group: read/write
  • Others: read only
  • Use when: Multiple containers share the same group and need write access

• 000: Files: 666 (rw-rw-rw-), Directories: 777 (rwxrwxrwx)

  • Everyone: full access
  • Use when: Not recommended (security risk)

Troubleshooting

Permission Denied Errors

Symptom:

Permission denied: Access to the path '/music/Artist/Album/track.flac' is denied.

Diagnosis:

1. Check file ownership:

   ls -la /path/to/music/Artist/Album/
   

2. Check what user Lidarr runs as:

   docker exec lidarr id
   

3. Check what user SoulSync runs as:

   docker exec soulsync-webui id
   

Fix: Ensure both containers use the same PUID/PGID

Files Created with Wrong Owner

Symptom: Files show as 1000:1000 even though you set PUID=99 PGID=100

Cause: Container needs to be rebuilt after changing PUID/PGID

Fix:

docker-compose down
docker-compose up -d

Existing Files Have Wrong Permissions

Symptom: Old files created before changing PUID/PGID have wrong ownership

Fix: Manually fix ownership:

# Find your download directory
docker exec soulsync-webui ls -la /app/downloads

# Fix ownership (run on host, not in container)
sudo chown -R 99:100 /path/to/downloads

Advanced: Custom Entrypoint

The container uses /entrypoint.sh to handle PUID/PGID. When the container starts:

1. Reads PUID, PGID, UMASK environment variables
2. Changes the internal soulsync user to match those IDs
3. Fixes permissions on app directories
4. Starts Python app as that user

You can verify this by checking container logs:

docker logs soulsync-webui

Look for:

🐳 SoulSync Container Starting...
📝 User Configuration:
   PUID: 99
   PGID: 100
   UMASK: 002
🔧 Adjusting user permissions...
   Changing group ID from 1000 to 100
   Changing user ID from 1000 to 99
🚀 Starting SoulSync Web Server...

Example docker-compose.yml

version: '3.8'

services:
  soulsync:
    image: boulderbadgedad/soulsync:latest
    container_name: soulsync-webui
    environment:
      # Match these to your Lidarr/Plex/other containers
      - PUID=99
      - PGID=100
      - UMASK=002
      - TZ=America/New_York
    ports:
      - "8008:8008"
    volumes:
      - ./config:/app/config
      - ./logs:/app/logs
      - ./downloads:/app/downloads
      - /mnt/user/Music:/music:rw    # Shared music library
    restart: unless-stopped

Need Help?

If you're still experiencing permission issues:

1. Check container logs: docker logs soulsync-webui
2. Verify PUID/PGID: docker exec soulsync-webui id
3. Check file permissions: docker exec soulsync-webui ls -la /app/downloads
4. Open an issue on GitHub with the output of these commands