From e2b8cc2e35fde862246284e94d5f8483d18066aa Mon Sep 17 00:00:00 2001
From: Broque Thomas <batmanesignal@gmail.com>
Date: Wed, 10 Dec 2025 13:46:22 -0800
Subject: [PATCH] Create DOCKER-TRANSFER-GUIDE.md

---
 DOCKER-TRANSFER-GUIDE.md | 204 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 204 insertions(+)
 create mode 100644 DOCKER-TRANSFER-GUIDE.md

diff --git a/DOCKER-TRANSFER-GUIDE.md b/DOCKER-TRANSFER-GUIDE.md
new file mode 100644
index 00000000..bd3435f2
--- /dev/null
+++ b/DOCKER-TRANSFER-GUIDE.md
@@ -0,0 +1,204 @@
+# Docker Transfer Folder Setup Guide
+
+## Problem: Files Download but Don't Transfer to Music Library
+
+This happens when the transfer path isn't properly configured in Docker.
+
+## Solution
+
+### 1. Docker Compose Volume Setup
+
+Your `docker-compose.yml` should look like this:
+
+```yaml
+version: '3.8'
+
+services:
+  soulsync:
+    image: boulderbadgedad/soulsync:latest
+    container_name: soulsync-webui
+    ports:
+      - "8008:8008"
+      - "8888:8888"
+      - "8889:8889"
+    volumes:
+      # Config and logs
+      - /home/myname/apps/soulsync/config:/app/config
+      - /home/myname/apps/soulsync/logs:/app/logs
+
+      # Downloads from slskd
+      - /mnt/data/slskd/downloads:/app/downloads
+
+      # Your Plex music library (transfer destination)
+      - /mnt/data/media/music:/app/Transfer:rw
+
+      # Database - USE NAMED VOLUME (critical!)
+      - soulsync_database:/app/database
+
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+
+    restart: unless-stopped
+
+volumes:
+  soulsync_database:
+    driver: local
+```
+
+**IMPORTANT**:
+- Do NOT mount `/app/database` to a host path
+- Use a named volume `soulsync_database:/app/database`
+- Host path mounts cause database corruption
+
+### 2. SoulSync Settings Configuration
+
+In SoulSync Web UI → Settings:
+
+1. **Download Path**: `/app/downloads`
+2. **Transfer Path**: `/app/Transfer`
+
+**DO NOT use host paths** like `/mnt/data/...` in settings. Use the **container paths** (`/app/...`).
+
+### 3. Enable Debug Logging
+
+**New Feature**: You can now change log level without restart!
+
+1. Go to Settings page
+2. Scroll to **"Log Level"** dropdown
+3. Change from **INFO** to **DEBUG**
+4. Click Save Settings
+5. Check logs at `logs/app.log` for detailed transfer information
+
+### 4. HTTP 429 (Too Many Requests) Fix
+
+This happens when too many concurrent downloads hit slskd. SoulSync has rate limiting, but slskd may need adjustment.
+
+**Option 1: Increase slskd limits** (recommended)
+Edit your slskd config (`appsettings.yml`):
+```yaml
+limits:
+  download:
+    maximum_concurrent_downloads: 10  # Increase from default
+```
+
+**Option 2: Reduce SoulSync workers**
+In SoulSync settings → `config.json`:
+```json
+{
+  "database": {
+    "path": "database/music_library.db",
+    "max_workers": 3  // Reduce from 5 to 3
+  }
+}
+```
+
+### 5. Understanding the Workflow
+
+```
+1. slskd downloads → /mnt/data/slskd/downloads (host)
+                  → /app/downloads (container)
+
+2. SoulSync processes files
+
+3. SoulSync moves to → /app/Transfer (container)
+                    → /mnt/data/media/music (host)
+                    → Your Plex library sees the files!
+```
+
+### 6. Troubleshooting
+
+**Files stay in downloads folder:**
+- Check transfer path is `/app/Transfer` (not host path)
+- Enable DEBUG logging and check for errors
+- Verify permissions: `chmod -R 755 /mnt/data/media/music`
+
+**Database errors when mounting volume:**
+```yaml
+# ❌ WRONG - causes corruption
+volumes:
+  - /home/myname/apps/soulsync/database:/app/database
+
+# ✅ CORRECT - use named volume
+volumes:
+  - soulsync_database:/app/database
+```
+
+**Tracks marked as failed but downloaded:**
+- This is the HTTP 429 issue
+- Files still download, but API reports failure
+- Check wishlist - these tracks can be removed
+- Fix by adjusting rate limits (see #4 above)
+
+**Excessive M3U saves:**
+- This is expected behavior for playlist sync
+- Not an error, just verbose logging
+- Change to INFO level if it bothers you
+
+### 7. Verify Setup
+
+Run these commands to verify:
+
+```bash
+# Check container can write to music library
+docker exec soulsync-webui touch /app/Transfer/test.txt
+ls -la /mnt/data/media/music/test.txt  # Should exist
+
+# Check downloads folder
+docker exec soulsync-webui ls -la /app/downloads
+
+# View logs in real-time
+docker logs -f soulsync-webui
+
+# Check database volume exists
+docker volume ls | grep soulsync
+```
+
+### 8. Complete Example
+
+**docker-compose.yml**:
+```yaml
+version: '3.8'
+
+services:
+  soulsync:
+    image: boulderbadgedad/soulsync:latest
+    container_name: soulsync-webui
+    environment:
+      - PUID=1000
+      - PGID=1000
+      - TZ=America/New_York
+    ports:
+      - "8008:8008"
+      - "8888:8888"
+      - "8889:8889"
+    volumes:
+      - ./config:/app/config
+      - ./logs:/app/logs
+      - /mnt/data/slskd/downloads:/app/downloads
+      - /mnt/data/media/music:/app/Transfer:rw
+      - soulsync_database:/app/database
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    restart: unless-stopped
+
+volumes:
+  soulsync_database:
+    driver: local
+```
+
+**SoulSync Settings**:
+- slskd URL: `http://host.docker.internal:5030`
+- Download Path: `/app/downloads`
+- Transfer Path: `/app/Transfer`
+- Log Level: `DEBUG` (for troubleshooting)
+
+---
+
+## Still Having Issues?
+
+1. Enable DEBUG logging
+2. Download a single track
+3. Check `logs/app.log` for the complete flow
+4. Post relevant log excerpts in the GitHub issue
+
+The logs will show exactly where the transfer is failing.