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.

variabledefaultwhat
NAVIDROME_URLhttp://navidrome:4533Your 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.
PORT8080Port the server listens on.
DATA_DIR./dataWhere 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_DAYS30A browser that isn't used for this long is signed out.
COVER_CACHE_MB1024Disk for resized covers; least recently used are deleted first.
LRCLIB_URLhttps://lrclib.netWhere lyrics Navidrome doesn't have are looked up. Empty turns LRCLIB off.
LYRICS_BACKFILLonon: walk the library in the background (about one song a second) to fetch lyrics nobody opened yet. off to disable.
LYRICS_WRITE_LRCoffon: 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_URLhttps://musicbrainz.orgWhere 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_GEToffon: 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_MODELopenai/gpt-oss-120bThe Groq model for playlists from a prompt.
GROQ_URLhttps://api.groq.com/openai/v1Groq'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_SESSIONonon: 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_SEEDoffon: 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_PROXYfalsetrue behind a reverse proxy: client IPs come from X-Real-IP / X-Forwarded-For (login rate limits).
UPDATE_CHECKoffon: 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.