diff --git a/UNRAID.md b/UNRAID.md new file mode 100644 index 00000000..91fa0379 --- /dev/null +++ b/UNRAID.md @@ -0,0 +1,257 @@ +# 🏠 SoulSync Unraid Installation Guide + +Complete guide to running SoulSync on Unraid with proper path mapping and configuration. + +## 🎯 Why SoulSync on Unraid? + +- **24/7 Operation**: Perfect for background music automation +- **Centralized Storage**: All your media in one place +- **Docker Integration**: Native Docker support with easy management +- **Media Server Ready**: Plex/Jellyfin likely already running + +## 🚀 Installation Methods + +### Method 1: Docker Run Command (Quick) + +```bash +docker run -d \ + --name=soulsync \ + -p 8008:8008 \ + -p 8888:8888 \ + -p 8889:8889 \ + -v /mnt/user/appdata/soulsync/config:/app/config \ + -v /mnt/user/appdata/soulsync/logs:/app/logs \ + -v /mnt/user/Music:/host/music:rw \ + -v soulsync_database:/app/database \ + --restart unless-stopped \ + boulderbadgedad/soulsync:latest +``` + +### Method 2: Unraid Template (Recommended) + +Create `/boot/config/plugins/dockerMan/templates-user/soulsync.xml`: + +```xml + + + SoulSync + boulderbadgedad/soulsync:latest + https://hub.docker.com/r/boulderbadgedad/soulsync + bridge + + bash + false + https://github.com/Nezreka/SoulSync + https://github.com/Nezreka/SoulSync + Automated music discovery and collection manager. Sync Spotify/Tidal/YouTube playlists to Plex/Jellyfin via Soulseek. + MediaApp:Music + http://[IP]:[PORT:8008] + + https://raw.githubusercontent.com/Nezreka/SoulSync/main/assets/trans.png + --restart unless-stopped + + + 1704067200 + Support Development + https://ko-fi.com/boulderbadgedad + slskd container or standalone installation + 8008 + 8888 + 8889 + /mnt/user/appdata/soulsync/config + /mnt/user/appdata/soulsync/logs + /mnt/user/Music + + +``` + +## 📁 Unraid Path Structure + +### Typical Unraid Paths +``` +/mnt/user/Music/ # Your main music share +├── Downloads/ # slskd download folder +├── Library/ # Organized music library +└── Transfer/ # Processing folder + +/mnt/user/appdata/soulsync/ # App configuration +├── config/ # SoulSync settings +└── logs/ # Application logs +``` + +## ⚙️ Configuration for Unraid + +### 1. Service URLs +In SoulSync settings, use these URLs: + +- **slskd**: `http://192.168.1.100:5030` (replace with your Unraid IP) +- **Plex**: `http://192.168.1.100:32400` +- **Jellyfin**: `http://192.168.1.100:8096` + +### 2. Download/Transfer Paths +Set these paths in SoulSync settings: + +- **Download Path**: `/host/music/Downloads` +- **Transfer Path**: `/host/music/Library` + +### 3. slskd Integration +If running slskd on Unraid: +```bash +# slskd container should mount the same music share +docker run -d \ + --name=slskd \ + -p 5030:5030 \ + -p 50300:50300 \ + -v /mnt/user/appdata/slskd:/app \ + -v /mnt/user/Music/Downloads:/downloads \ + -v /mnt/user/Music/Shares:/shares:ro \ + slskd/slskd:latest +``` + +## 🚦 Setup Steps + +### 1. Install Prerequisites +- Install slskd container from Community Applications +- Ensure Plex/Jellyfin is running (if desired) +- Create Spotify API app at https://developer.spotify.com + +### 2. Install SoulSync +```bash +# Option 1: Community Applications +Search for "SoulSync" in CA and install + +# Option 2: Manual Docker Run +Use the docker run command above + +# Option 3: Unraid Docker UI +Add container manually with repository: boulderbadgedad/soulsync:latest +``` + +### 3. Configure Paths +Map these volumes in Unraid Docker settings: +- Container: `/app/config` → Host: `/mnt/user/appdata/soulsync/config` +- Container: `/app/logs` → Host: `/mnt/user/appdata/soulsync/logs` +- Container: `/host/music` → Host: `/mnt/user/Music` (or your music share) + +### 4. Configure Ports +- `8008` - Main web interface +- `8888` - Spotify OAuth callback +- `8889` - Tidal OAuth callback + +## 🎵 First-Time Setup + +1. **Access SoulSync**: Navigate to `http://your-unraid-ip:8008` +2. **Go to Settings**: Configure your API credentials +3. **Set Paths**: Use `/host/music/Downloads` and `/host/music/Library` +4. **Test Connections**: Verify all services connect properly + +## 🔧 Unraid-Specific Benefits + +### File Management +- **User Shares**: Automatic organization across multiple drives +- **Cache Drive**: Fast processing for downloads +- **Parity Protection**: Your music library is protected + +### Networking +- **Bridge Mode**: Simple port mapping +- **Custom Networks**: Isolate containers if desired +- **VPN Support**: Route through VPN containers if needed + +### Monitoring +- **Unraid Dashboard**: Monitor container status +- **CA Auto Update**: Keep SoulSync updated automatically +- **Resource Monitoring**: Track CPU/RAM usage + +## 📊 Recommended Share Setup + +### Music Share Configuration +``` +Share Name: Music +Allocation Method: High Water +Minimum Free Space: 10GB +Split Level: 2 +Include: disk1,disk2,cache +Exclude: (none) +Use Cache: Yes (cache:yes) +``` + +This ensures: +- Fast downloads to cache drive +- Automatic migration to array +- Proper organization across multiple drives + +## 🛠️ Troubleshooting + +### Container Won't Start +```bash +# Check Unraid logs +docker logs soulsync + +# Verify paths exist +ls -la /mnt/user/appdata/soulsync/ +ls -la /mnt/user/Music/ +``` + +### Services Not Connecting +- Use Unraid server IP, not `localhost` or `127.0.0.1` +- Check firewall settings in Unraid network settings +- Verify other containers are running and accessible + +### Permission Issues +```bash +# Fix ownership on appdata +chown -R nobody:users /mnt/user/appdata/soulsync/ + +# Fix music share permissions +chmod -R 775 /mnt/user/Music/ +``` + +## 🚀 Advanced Configuration + +### Custom Network +```bash +# Create custom network +docker network create soulsync-network + +# Run with custom network +docker run --network soulsync-network ... +``` + +### Resource Limits +In Unraid Docker settings: +- **CPU Pinning**: Pin to specific cores +- **Memory Limit**: Set RAM limit (2GB recommended) +- **CPU Shares**: Set priority vs other containers + +### Auto-Update +Install "CA Auto Update Applications" plugin: +- Automatically updates SoulSync container +- Sends notifications on updates +- Maintains configuration + +## 📱 Accessing SoulSync + +- **Local**: `http://tower.local:8008` (if using .local domains) +- **IP Address**: `http://192.168.1.100:8008` +- **Reverse Proxy**: Configure nginx/traefik for external access + +## 🎯 Perfect Unraid Setup + +``` +Container Stack: +├── SoulSync (Music automation) +├── slskd (Soulseek client) +├── Plex/Jellyfin (Media server) +├── *arr Apps (Optional: Lidarr integration) +└── Reverse Proxy (Optional: External access) +``` + +This creates a complete, automated music ecosystem on Unraid! + +## 📝 Support + +- SoulSync logs: `/mnt/user/appdata/soulsync/logs/` +- Unraid diagnostics: Tools → Diagnostics +- Container logs: Docker tab → SoulSync → Logs + +Your music automation server is ready! 🎵 \ No newline at end of file