Skip to content

About

Self-hosted music stack: Jellyfin serves a deduplicated symlink union of Deemix (Deezer) and Lidarr/Soulseek downloads; stdlib-only Python tools migrate, union and sync playlists, automated by a watcher sidecar. Download traffic egresses through Gluetun (IPVanish VPN) and a Tailscale sidecar serves every web UI to the tailnet.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Home music stack

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
Loading

Services (docker-compose.yml)

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 deemix

Tools

Three 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

Workflow: download → import

  1. 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>.m3u8 is written at the library root.
  2. library-watcher takes it from there: once the source trees settle it runs migrate (dedups and places loose tracks) → union_library (refreshes the union root) → import. To run the import by hand instead:
    python3 -m reorganize_playlists import
    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 archives errors.txt/cover.jpg and 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).

Documentation

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

Developing

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.

About

Self-hosted music stack: Jellyfin serves a deduplicated symlink union of Deemix (Deezer) and Lidarr/Soulseek downloads; stdlib-only Python tools migrate, union and sync playlists, automated by a watcher sidecar. Download traffic egresses through Gluetun (IPVanish VPN) and a Tailscale sidecar serves every web UI to the tailnet.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages