docs/configuration.md
Configuration
Everything is an environment variable. Only NAVIDROME_URL usually needs setting. A bad value stops the server at
boot with a message naming the variable.
| variable | default | what |
|---|---|---|
NAVIDROME_URL | http://navidrome:4533 | Your Navidrome (or any OpenSubsonic server), as this container reaches it. Usually the internal Docker address. |
NAVIDROME_SERVERS | — | Several servers to choose from at sign-in, as id=url pairs separated by commas (home=http://navidrome:4533,friend=https://music.example.com). Replaces NAVIDROME_URL. The browser can only ever pick from this list. |
PORT | 8080 | Port the server listens on. |
DATA_DIR | ./data | Where sessions, the search and lyrics index, history and the cover cache live. Mount a volume here (/data in the image). |
SESSION_SECRET | — | Encrypts stored Navidrome credentials. Unset: a random one is generated once and kept in DATA_DIR. |
SESSION_IDLE_DAYS | 30 | A browser that isn't used for this long is signed out. |
COVER_CACHE_MB | 1024 | Disk for resized covers; least recently used are deleted first. |
LRCLIB_URL | https://lrclib.net | Where lyrics Navidrome doesn't have are looked up. Empty turns LRCLIB off. |
LYRICS_BACKFILL | on | on: walk the library in the background (about one song a second) to fetch lyrics nobody opened yet. off to disable. |
LYRICS_WRITE_LRC | off | on: lyrics found on LRCLIB are also saved as <track>.lrc next to the audio file, so other clients get them. Needs MUSIC_DIR and Navidrome's "Report Real Path". Never overwrites; undo from the lyrics page. |
LYTERION_URL | — | Lyterion's API, as this container reaches it, to show what of your Spotify library is in Navidrome on the import page. Empty: the import page asks for a Spotify export file instead. |
LYTERION_TOKEN | — | The LYTERION_PLAYER_TOKEN set on Lyterion. Needed with LYTERION_URL. |
MUSICBRAINZ_URL | https://musicbrainz.org | Where new releases by the artists you follow are looked up, once a week (artist names only, one request a second). Empty turns the new releases row off. |
RELEASES_AUTO_GET | off | on: with Lyterion set up, new releases by followed artists are handed to it on their own (at most ten a week). off: they are only listed, and get it on a release hands that one over. |
GROQ_API_KEY | — | Turns on playlists from a prompt ("rainy sunday, slow, warm"): Groq picks artists from your library and the player builds the list from songs you own. Kept server-side. Empty: off. |
GROQ_MODEL | openai/gpt-oss-120b | The Groq model for playlists from a prompt. |
GROQ_URL | https://api.groq.com/openai/v1 | Groq's API, or any OpenAI-compatible one. |
AUDIOMUSE_URL | — | AudioMuse-AI, as this container reaches it: song features (tempo, key, energy, mood) are copied into the index for bpm: / energy: / mood: search filters, smart shuffle and sonic neighbours. Empty: off, everything else works as is. |
FEEDBACK_GITHUB_TOKEN | — | A GitHub token that may open issues and write contents on FEEDBACK_REPO: turns on "send feedback" in the user menu, filed as an issue (screenshots go to a feedback branch). Empty: off. |
FEEDBACK_REPO | — | Where feedback goes, as owner/repo. Needed with FEEDBACK_GITHUB_TOKEN. |
ONE_SESSION | on | on: all of an account's open players share one playback session, like Spotify Connect: one plays, the others are remotes, and the device picker moves playback. off: every tab plays on its own. |
UPLOAD_DIR | — | Where music uploaded from the player lands (admins only), mounted writable. An import inbox (beets, Lyterion) or Navidrome's music folder. Empty turns uploads off. |
MUSIC_DIR | — | Navidrome's music folder mounted writable here, for LYRICS_WRITE_LRC. Unused otherwise. |
INDEX_USER | — | Navidrome account for background jobs (search index, lyrics backfill). Unset: the admin who signed in most recently. |
INDEX_PASSWORD | — | Password for INDEX_USER. |
DEMO_SEED | off | on: fill INDEX_USER's history with months of generated listening, once (for demos and previews, see docs/previews.md). Needs INDEX_USER. |
REDIS_URL | — | redis://…: keep computed answers (made for you) in Redis, shared by several instances. Unset: in memory, which is all one instance needs. |
TRUST_PROXY | false | true behind a reverse proxy: client IPs come from X-Real-IP / X-Forwarded-For (login rate limits). |
UPDATE_CHECK | off | on: admins see when a newer release is out (one request to GitHub a day). The other outside calls are lyrics lookups (LRCLIB_URL), new releases (MUSICBRAINZ_URL) and Groq when GROQ_API_KEY is set. |