Deemix downloads music into one library on disk and the Lidarr stack into another. union_library merges them into a single deduplicated union root of symlinks that Jellyfin serves, laid out so every song can be browsed by its real artist and album. Playlists are Jellyfin playlists you edit in the Jellyfin UI. A library-watcher sidecar polls the source trees and runs the migrate → union → import pipeline automatically when they change (ADR 0005). Vocabulary: CONTEXT.md.
flowchart TD
D["Deemix<br>Deezer downloads"] --> DL["$MUSIC_DIR/Deemix<br>library root"]
LS["Lidarr stack<br>Lidarr · Prowlarr · Soularr · Slskd · Transmission"] --> LL["$MUSIC_DIR/Lidarr/media/music"]
DL -- "migrate: dedup and place" --> U
LL --> U["union_library"]
U -- "one symlink per album" --> UR["$MUSIC_DIR/Jellyfin<br>union root"]
UR -- "the only directory scanned" --> J["Jellyfin"]
W["library-watcher"] -. "on change: migrate → union → import" .-> U
| Service | Image (pinned) | Port | Volumes |
|---|---|---|---|
jellyfin |
jellyfin/jellyfin:12.4 |
8096/tcp (web), 7359/udp (discovery) | ./config → /config, ./cache → /cache, $MUSIC_DIR/Jellyfin → /media (union root), $MUSIC_DIR/Deemix → /Deemix:ro, $MUSIC_DIR/Lidarr → /Lidarr:ro |
deemix |
ghcr.io/bambanah/deemix:v4.8.0 |
6595 (web) | $MUSIC_DIR/Deemix → /downloads, ./deemix-config → /config |
library-watcher |
built from docker/library-watcher/ (python:3.13.18-alpine + git) |
— | repo → /tools:ro, $MUSIC_DIR → $MUSIC_ROOT (/music) |
gluetun |
qmcgaw/gluetun:v3 |
publishes 9696, 5030, 5031, 50300, 9091, 51413 (t/u), 8191 | — (IPVanish creds from .env) |
lidarr |
ghcr.io/hotio/lidarr:latest |
8686 (web) | ./lidarr → /config, ${DATA_DIR} → /data |
prowlarr † |
ghcr.io/hotio/prowlarr:latest |
9696 (web) | ./prowlarr → /config, ${DATA_DIR} → /data |
flaresolverr † |
ghcr.io/flaresolverr/flaresolverr:latest |
8191 | stateless — tmpfs /tmp for browser profiles |
soularr |
mrusse08/soularr:latest |
8265 (web) | ./soularr → /data (holds config.ini), ${DATA_DIR}/slskd/{downloads,incomplete} |
slskd † |
slskd/slskd |
5030 (web), 5031 (https), 50300 (slsk listen) | ./slskd → /app, ${DATA_DIR}/slskd/{downloads,incomplete}, ${DATA_DIR}/media → /data:ro, $MUSIC_DIR/Deemix → /deemix:ro |
transmission † |
lscr.io/linuxserver/transmission:latest |
9091 (web), 51413 (t/u peer) | ./transmission → /config, ${DATA_DIR}/torrents → /data/torrents |
tailscale |
tailscale/tailscale:latest |
tailnet 443, 8443–8448 | ./tailscale/state → /var/lib/tailscale, ./tailscale/serve.json → /config/serve.json:ro |
† Routed services (prowlarr, flaresolverr, slskd, transmission) share gluetun's network namespace via network_mode: service:gluetun: all their traffic egresses through the IPVanish OpenVPN tunnel (gluetun's firewall is the kill switch), they reach each other on localhost, and their ports are published on the gluetun service — so the localhost:<port> URLs above still work on the host. tailscale serves every web UI to the tailnet over HTTPS per tailscale/serve.json. Spec 0005: gluetun-vpn-tailscale.
jellyfin/deemix/library-watcher run as uid/gid 502; the Lidarr stack runs as PUID/PGID from .env (502:20 on this host — FlareSolverr ignores them, its image uses a fixed user). $MUSIC_DIR (.env) is the host tree the Deemix/Lidarr/Jellyfin folders live under. cache/ and .env are git-ignored, as is almost all of config/ (db, metadata, logs), deemix-config/ (credentials, queue, logs — they used to live in the music library), and the Lidarr stack's app dirs (lidarr/, prowlarr/, slskd/, soularr/, transmission/, tailscale/ — runtime state + secrets). The small settings files are tracked so changes are visible in diffs: config/config/*.xml, config/root/, config/plugins/configurations/, deemix-config/config.json, soularr/config.ini.example, slskd/slskd.yml.example, tailscale/serve.json.example. Secrets never live in tracked files — they come from .env (see docs/reference/lidarr-stack.md).
docker compose up -d # start everything (or name services to start a subset)
docker compose stop jellyfin # e.g. before moving files
docker compose logs -f deemixThree stdlib-only Python packages live in this repo; run them from the repo root.
| Tool | Command | What it does |
|---|---|---|
reorganize_playlists |
python3 -m reorganize_playlists <cmd> |
migrate dedups/places loose tracks, import merges Deemix .m3u8s into Jellyfin playlists, export, retag, rollback |
union_library |
python3 -m union_library |
Rebuilds the union root's symlinks to match the source trees |
library_watcher |
runs as the library-watcher service |
Polls the source trees and runs migrate → union → import on change |
- Open Deemix at http://localhost:6595 and download playlists (or add an artist in Lidarr — see add-music). Tracks land straight in album folders, and one
<Playlist>.m3u8is written at the library root. library-watchertakes it from there: once the source trees settle it runsmigrate(dedups and places loose tracks) →union_library(refreshes the union root) →import. To run the import by hand instead:It scans Jellyfin and waits for the scan to finish. It appends songs that are new on Deezer to the matching Jellyfin playlist without undoing your edits, and reports songs Deezer dropped. It archivespython3 -m reorganize_playlists import
errors.txt/cover.jpgand uploads the cover, moves the playlist file out of the library, exports all playlists and the inventory, and commits to the library's git repo (never pushed).
The docs follow the Diátaxis framework — see docs/README.md for the full map.
| Quadrant | Contents |
|---|---|
| How-to (docs/how-to/) | Setup, wiring the Lidarr stack, adding music, the union-root cutover, the one-off migration, upgrading pinned images, VPN + Tailscale access |
| Reference (docs/reference/) | Library layout rules, key settings, reorganize_playlists, union_library, Lidarr stack, CONTEXT.md |
| Explanation (docs/explanation/) | Architecture, ADRs, specs, research notes, retired dedup_music |
| Tutorials | none yet — setup is the closest to a first-run walkthrough |
python3 -m unittest # full suite
python3 -m unittest tests.test_import # one file
.venv/bin/mypy # strict typecheck (python3 -m venv .venv && .venv/bin/pip install mypy)Tools are stdlib-only; keep them that way. Test through the main(argv, fakes) seams described in AGENTS.md.