Version & Updates: Click the version number in the sidebar footer to open the What's New modal, which shows detailed release notes for every feature and fix. SoulSync automatically checks for updates by comparing your running version against the latest GitHub commit. If an update is available, a banner appears in the modal. Docker users are notified when a new image has been pushed to the repo.
SoulSync uses three folders to manage your music files. Most setup issues come from incorrect folder configuration — especially in Docker. Read this section carefully.
docker-compose.yml
/app/downloads
/app/Transfer
/app/Staging
Artist/Album/01 - Title.flac
In Docker, every app runs in its own isolated container with its own filesystem. Volume mounts in docker-compose create "bridges" between your host folders and the container. But SoulSync doesn't automatically know where those bridges go — you have to tell it via the Settings page.
Here's what happens with a properly configured setup:
/mnt/data/slskd-downloads/
/mnt/media/music/
/mnt/data/slskd-downloads
/mnt/media/music
/app/downloads/
/app/Transfer/
Many users set up their docker-compose volumes correctly but never open SoulSync Settings to configure the paths. The app defaults may not match your volume mounts. You must go to Settings → Download Settings and verify that:
The Download Path in SoulSync must point to the exact same physical folder where slskd saves its completed downloads. If they don't match, SoulSync can't find the files and post-processing fails silently.
/downloads/complete
- /mnt/data/slskd-downloads:/downloads/complete
- /mnt/data/slskd-downloads:/app/downloads
If you're running in Docker, the paths you enter in SoulSync's Settings page must be container-side paths (the right side of the : in your volume mount), not host paths (the left side). SoulSync runs inside the container and can only see its own filesystem.
:
/mnt/music
./downloads
Your Transfer Path must ultimately point to the same physical directory your media server monitors. This is how new music appears in Plex/Jellyfin/Navidrome.
- /mnt/media/music:/app/Transfer:rw
Here's a working example showing both slskd and SoulSync configured to share the same download folder:
# docker-compose.yml
services:
slskd:
image: slskd/slskd:latest
volumes:
# slskd saves completed downloads here
- /mnt/data/slskd-downloads:/downloads
- /docker/slskd/config:/app
soulsync:
image: boulderbadgedad/soulsync:latest
# SAME host folder as slskd — this is the key!
# Your media server's music folder
# Config, logs, staging, database
- /docker/soulsync/config:/app/config
- /docker/soulsync/logs:/app/logs
- /docker/soulsync/staging:/app/Staging
- soulsync_database:/app/data
# Then in SoulSync Settings:
# Download Path: /app/downloads
# Transfer Path: /app/Transfer
Go through every item. If you miss any single one, the pipeline will break:
:rw
http://slskd:5030
http://host.docker.internal:5030
id
If paths are correct but files still won't transfer, it's usually a permissions issue. SoulSync needs read + write access to all three folders.
PUID
PGID
chmod -R 755 /mnt/media/music
Run these commands to confirm everything is wired up correctly:
docker exec soulsync-webui ls -la /app/downloads
docker exec soulsync-webui touch /app/Transfer/test.txt && echo "OK"
test.txt
rm /mnt/media/music/test.txt
docker exec soulsync-webui id
logs/app.log
docker exec soulsync-webui ls /app/downloads
chmod -R 755
/mnt/media/music:/app/Transfer
SoulSync runs in Docker with the following environment variables:
SOULSYNC_COMMIT_SHA
Key volume mounts: Map your download path, transfer path (media server's monitored folder), and staging path to host directories. Ensure the paths configured in SoulSync Settings match the container-side mount points.
Your docker-compose volumes section must include these mappings. The left side is your host path, the right side is where SoulSync sees it inside the container:
volumes
/app/config
config.json
/app/logs
app.log
post-processing.log
/app/data
soulsync_database:/app/data
Podman / Rootless Docker: SoulSync supports Podman rootless (keep-id) and rootless Docker setups. The entrypoint handles permission alignment automatically.
Config migration: When upgrading from older versions, SoulSync automatically migrates settings from config.json to the database on first startup. No manual migration is needed.