docs/self-hosting.md

Self-hosting

The whole stack on one machine: Navidrome serving your files, lodesong in front of it, and the extras you want (uploads, playlists from a prompt, a domain with HTTPS, Lyterion). Written so a person or a coding agent can follow it top to bottom.

For coding agents. Follow the steps in order. A line marked ask is a choice for the person: ask it and wait. Never print a secret (passwords, API keys, tokens) to the chat; write them to .env and refer to them by name. Every step ends with a check and the output to expect. Stop and report if a check doesn't match, and finish with check it works.

0. Decide

ask each of these first; the rest of the guide branches on the answers.

choicedefault
Navidromealready running, or a new one with this stacknew
musicthe folder your music is in (it is mounted read-only)~/music
addresslocal only (http://<machine>:8080) or a domain with HTTPSlocal
uploadsupload from the browser: into a tagging inbox (beets, Lyterion) or straight into the music folder, or offoff
prompt playlistsa Groq API key for "rainy sunday, slow, warm" playlists, or offoff
Lyterionbring a Spotify library over with Lyterion, or notnot

1. Requirements

  • Linux or macOS with Docker 24+ and the compose plugin. The image is amd64 (a Mac with Apple silicon runs it through Docker's emulation; fine for trying, slow for a library of thousands of songs).
  • The music folder readable by uid 1000 (Navidrome's and lodesong's user).
sh
1docker compose version # Docker Compose version v2.x
2uname -m # x86_64 (or arm64: emulated, see above)
3ls "$MUSIC" | head # your artist folders

2. Write the stack

sh
1mkdir -p ~/lodesong && cd ~/lodesong

compose.yaml. With an existing Navidrome, drop the navidrome service and set NAVIDROME_URL to the address this container reaches it at (usually its service name on a shared Docker network, not localhost).

yaml
1services:
2 navidrome:
3 image: deluan/navidrome:latest
4 restart: unless-stopped
5 environment:
6 ND_SCANSCHEDULE: 1h
7 ND_LYRICSPRIORITY: .lrc,embedded
8 volumes:
9 - navidrome-data:/data
10 - ${MUSIC_DIR}:/music:ro
11 ports:
12 - "4533:4533" # Navidrome's own UI, for the first admin; remove later if you like
13
14 player:
15 image: ghcr.io/findmalek/lodesong:latest
16 restart: unless-stopped
17 depends_on: [navidrome]
18 env_file: .env
19 environment:
20 NAVIDROME_URL: http://navidrome:4533
21 ports:
22 - "8080:8080"
23 volumes:
24 - player-data:/data
25 # uploads (step 4): - ${UPLOAD_HOST_DIR}:/inbox
26 read_only: true
27 tmpfs: [/tmp]
28
29volumes:
30 navidrome-data:
31 player-data:

.env (keep it out of git, chmod 600 .env):

sh
1MUSIC_DIR=/home/you/music
2# filled in by step 4 if you want them:
3# UPLOAD_DIR=/inbox
4# UPLOAD_HOST_DIR=/home/you/music-inbox
5# GROQ_API_KEY=
6# LYTERION_URL=
7# LYTERION_TOKEN=

Every other setting has a default: configuration.

3. Start it and make the first account

sh
1docker compose up -d
2docker compose ps # navidrome and player both "running" / "healthy"

ask the person to open http://<machine>:4533 and create the Navidrome admin there (Navidrome asks for it on the first visit; the person picks the password). Navidrome scans the music folder on start and every hour after.

Then open lodesong at http://<machine>:8080. Above the sign-in form it checks the server:

  • ✓ navidrome 0.6x · 12 ms: sign in with the Navidrome account.
  • ✗ can't reach navidrome: the container can't reach NAVIDROME_URL; see troubleshooting.

Check from the machine:

sh
1curl -s http://localhost:8080/api/health
2# {"status":"ok","version":"1.x.y","upstreams":[{"id":"default","reachable":true,...}]}

4. Extras

Each is independent; do the ones chosen in step 0, then docker compose up -d again.

Uploads

Songs and album folders uploaded from settings → library → upload land in UPLOAD_DIR inside the container, folders kept, never overwriting. Admins only.

  • Into a tagging inbox (recommended): mount an inbox folder that beets or Lyterion imports from, so uploads get proper tags and covers before Navidrome sees them.
  • Straight into the music folder: mount a writable sub-folder of the music folder; Navidrome picks the files up at its next scan. The /music mount of Navidrome stays read-only.
sh
1mkdir -p ~/music-inbox && sudo chown 1000:1000 ~/music-inbox
2# .env
3UPLOAD_DIR=/inbox
4UPLOAD_HOST_DIR=/home/you/music-inbox

Uncomment the /inbox volume line in compose.yaml.

Playlists from a prompt

sh
1# .env
2GROQ_API_KEY=gsk_... # write it, don't echo it

New playlist → "describe it". Groq gets the names of your artists (with song counts, years, genres and how much you play them) and answers with artists and an era; the playlist is built from songs you own. mixes

Your other devices

Nothing to set: every open lodesong tab of yours shares one playback session, with a device picker in the player bar. Phones use a Subsonic app (Arpeggi, Substreamer, Symfonium…) against Navidrome's address; the queue hands off both ways. devices · sync

Now playing in your terminal

Settings → sync → now playing in your terminal makes a token and a one-line command for Claude Code (/lodesong connect …) or the OpenCode plugin. devices

Lyterion

Follow lyterion: it runs next to this stack and writes into the same music folder.

5. A domain with HTTPS

ask for the domain and point its DNS at the machine. With Caddy in the same compose file:

yaml
1 caddy:
2 image: caddy:2
3 restart: unless-stopped
4 ports: ["80:80", "443:443"]
5 volumes:
6 - ./Caddyfile:/etc/caddy/Caddyfile:ro
7 - caddy-data:/data
8# and add caddy-data: under volumes
caddy
1music.example.com {
2 reverse_proxy player:8080
3}

Add TRUST_PROXY=true to .env (login rate limits then see the real client address) and remove the 8080:8080 port. Traefik, nginx and Dokploy: deploy. Whatever the proxy, it must pass WebSockets (the device picker and listen together use them) and must not buffer audio.

sh
1curl -sI https://music.example.com/healthz # HTTP/2 200

6. Keep it running

  • Updates: docker compose pull && docker compose up -d. Pin a version (lodesong:1.2.0) to update on your own schedule; releases list what changed.
  • Backups: the music folder (your files), the navidrome-data volume (accounts, playlists, likes, play counts) and the player-data volume (sessions, listening history, lyrics cache, synced settings). Back up .env somewhere private.

Check it works

Run these at the end and report each result:

checkhowexpect
containersdocker compose psevery service running, the player healthy
healthcurl -s http://localhost:8080/api/health"status":"ok", the upstream reachable: true
librarysign in, open albumsyour albums, with covers
playbackplay a songsound, the progress bar moving
lyricsopen lyrics (l) on a well-known songsynced or plain lyrics
uploads, if onsettings → library → upload, drop one file"done", the file in the inbox folder
prompt playlists, if onnew playlist → describe it → "make it"a name and "N of your songs"
domain, if setcurl -sI https://<domain>/healthz200

Something off: troubleshooting.