lodesong

Self-hosting

updated Nov 8, 2026

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).
docker compose version     # Docker Compose version v2.x
uname -m                   # x86_64 (or arm64: emulated, see above)
ls "$MUSIC" | head         # your artist folders

2. Write the stack

mkdir -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).

services:
  navidrome:
    image: deluan/navidrome:latest
    restart: unless-stopped
    environment:
      ND_SCANSCHEDULE: 1h
      ND_LYRICSPRIORITY: .lrc,embedded
    volumes:
      - navidrome-data:/data
      - ${MUSIC_DIR}:/music:ro
    ports:
      - "4533:4533" # Navidrome's own UI, for the first admin; remove later if you like

  player:
    image: ghcr.io/findmalek/lodesong:latest
    restart: unless-stopped
    depends_on: [navidrome]
    env_file: .env
    environment:
      NAVIDROME_URL: http://navidrome:4533
    ports:
      - "8080:8080"
    volumes:
      - player-data:/data
      # uploads (step 4): - ${UPLOAD_HOST_DIR}:/inbox
    read_only: true
    tmpfs: [/tmp]

volumes:
  navidrome-data:
  player-data:

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

MUSIC_DIR=/home/you/music
# filled in by step 4 if you want them:
# UPLOAD_DIR=/inbox
# UPLOAD_HOST_DIR=/home/you/music-inbox
# GROQ_API_KEY=
# LYTERION_URL=
# LYTERION_TOKEN=

Every other setting has a default: configuration.

3. Start it and make the first account

docker compose up -d
docker 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:

curl -s http://localhost:8080/api/health
# {"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.
mkdir -p ~/music-inbox && sudo chown 1000:1000 ~/music-inbox
# .env
UPLOAD_DIR=/inbox
UPLOAD_HOST_DIR=/home/you/music-inbox

Uncomment the /inbox volume line in compose.yaml.

With GROQ_API_KEY set too, each uploaded song gets fill missing tags with ai. lodesong reads the file's tags, and Groq gets those tags plus the folder and file name it came in with (never the audio) and proposes title, artist, album, year, genre and track number where one is missing or clearly garbled. You review it: missing ones start ticked, changes to a tag the file already has start unticked, and every value is editable. save accepted writes the ticked values to <song>.lodesong.json next to the song. It does not rewrite the tags inside the audio file (lodesong has no tag writer), and beets and Lyterion don't read that file on their own, so it is a record to apply or script from.

Playlists from a prompt

# .env
GROQ_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:

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

Add TRUST_PROXY=true to .env (login rate limits then see the real client address) and remove the 8080:8080 port. Set PUBLIC_URL=https://music.example.com too, so link previews point at the public address. 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.

curl -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.

On this page