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. |
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. |
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). Nothing else is ever sent anywhere. |