Ansible Role: Navidrome-docker

Install Navidrome Docker Compose project.

Navidrome is an open source web-based music collection server and streamer.

• https://www.navidrome.org/
• https://github.com/navidrome/navidrome/

Requirements

Requires the following to be installed:

• docker
• docker compose

Role Variables

Common Docker projects variables:

# Base directory for Docker projects
docker_projects_path: # /var/apps

Available role variables are listed below, along with default values (see defaults/main.yml):

# Docker project variables

navidrome_project_name: navidrome

# Docker project dynamic vars (uses `docker_project_name` prefix, adapt if overridden)

# Port targeted by Traefik router
navidrome_traefik_loadbalancer_server_port: 4533

# Main service additional docker-compose options (ex: cpu_shares, deploy, ...)
navidrome_service_additional_options: |
  #ports:
  #  - "4533:4533"

Base configuration:

# Navidrome project variables

# deluan/navidrome container version
navidrome_version: latest

# UID container is running as
navidrome_puid: "{{ ansible_facts['user_uid'] }}"
# GID container is running as
navidrome_pgid: "{{ ansible_facts['user_gid'] }}"


# Exposed service base URL
navidrome_baseurl: "https://music.example.net"

# Path to music collection on host
navidrome_music_volume: ./music

# Path to library backup directory on host
# (also set ND_BACKUP_PATH, ND_BACKUP_SCHEDULE and ND_BACKUP_COUNT in navidrome_env)
navidrome_backup_volume: # ex: ./backup


# Log level. Useful for troubleshooting. Possible values: error, warn, info, debug, trace
navidrome_loglevel: info

# Enable/disable the scanner. Set to false to disable automatic scanning of the music library.
navidrome_scanner_enabled: true
# Schedule for automatic scans. Use Cron syntax
navidrome_scanner_schedule: 0 # (disabled)

# How long Navidrome will wait before closing web ui idle sessions
navidrome_sessiontimeout: 24h

# Controls whether the server will run its Anonymous Data Collection feature to help improve the project.
navidrome_enableinsightscollector: true

Advanced configuration:
(see https://www.navidrome.org/docs/usage/configuration-options/#environment-variables)

navidrome_env:

  ## Comma-separated list of metadata agents to use for retrieving artist information, biographies, and images.
  ## Available agents: lastfm, spotify, and deezer. The order determines priority - agents are tried in the specified order until one succeeds.
  ## Only enabled and configured agents will be used.
  # ND_AGENTS: "lastfm,spotify,deezer"

  ## Change how album play count is computed. When set to "normalized", album play count will be divided by the number of album tracks.
  # ND_ALBUMPLAYCOUNTMODE: "absolute"

  ## How many login requests can be processed from a single IP during the AuthWindowLength. Set to 0 to disable the limit rater.
  # ND_AUTHREQUESTLIMIT: 5
  ## Window Length for the authentication rate limit.
  # ND_AUTHWINDOWLENGTH: "20s"

  ## Enable/disable .m3u playlist auto-import.
  # ND_AUTOIMPORTPLAYLISTS: true

  ## Use the client’s transcoding configuration for downloads, if the client does not specify the desired format.
  ## If false, the original format will be used, without any transcoding.
  # ND_AUTOTRANSCODEDOWNLOAD: false

  ## Set imported playlists as public by default.
  # ND_DEFAULTPLAYLISTPUBLICVISIBILITY: false

  ## Configure the order to look for artist images.
  # ND_ARTISTARTPRIORITY: "artist.*, album/artist.*, external"

  ## Configure a centralized folder for artist image lookups. When set and image-folder is included in ArtistArtPriority,
  ## Navidrome looks for images in this folder named after the artist’s MusicBrainz ID or name.
  # ND_ARTISTIMAGEFOLDER:

  ## Path to store backups. Set to "" to disable backups.
  # ND_BACKUP_PATH: "" # ex: "/data/backup"
  ## Schedule for automatic backups. Use Cron syntax.
  # ND_BACKUP_SCHEDULE: "" # ex: "15 6 * * 6" # At 06:15 on Saturday
  ## Number of backups to keep.
  # ND_BACKUP_COUNT: 0

  ## Configure the order to look for cover art images. Use special embedded value to get embedded images from the audio files.
  # ND_COVERARTPRIORITY: "cover.*, folder.*, front.*, embedded, external"
  ## Set JPEG quality percentage for resized cover art images.
  # ND_COVERARTQUALITY: 75

  ## Set this to false to completely disable Deezer integration for artist images.
  # ND_DEEZER_ENABLED: true
  ## Language to be used by Deezer integration.
  # ND_DEEZER_LANGUAGE: "en"

  ## Format to transcode to when client requests downsampling (specify maxBitrate without a format)
  # ND_DEFAULTDOWNSAMPLINGFORMAT: "opus"

  ## Sets the default language used by the UI when logging in from a new browser. This value must match one of the file names in the resources/i18n.
  ## Ex: for Chinese Simplified it has to be zh-Hans (case sensitive)
  # ND_DEFAULTLANGUAGE: "en"
  ## Sets the default theme used by the UI when logging in from a new browser. This value must match one of the options in the UI.
  # ND_DEFAULTTHEME: "Dark"

  ## Sets the default expiration time for new shares (public links). Accepts durations like “24h” or “45m”.
  # ND_DEFAULTSHAREEXPIRATION: "8760h" # (1 year)
  ## Sets the default downloadable state for new shares (public links). When enabled, newly created shares will be downloadable by default.
  # ND_DEFAULTDOWNLOADABLESHARE: false

  ## Sets the default volume used by the UI when logging in from a new browser. This value must be between 0 and 100.
  # ND_DEFAULTUIVOLUME: 100

  ## Configure the priority order for disc-level cover art sources in multi-disc albums. Uses the same pattern format as CoverArtPriority.
  ## The special keyword discsubtitle matches image files whose filenames equal the disc’s subtitle.
  # ND_DISCARTPRIORITY: "disc*.*, cd*.*, cover.*, folder.*, front.*, discsubtitle, embedded"
  ## Enable image pre-caching of new added music.
  # ND_ENABLEARTWORKPRECACHE: true
  ## Enable artwork upload functionality for playlists, artists, and internet radios via the web UI. Accepted formats: JPEG, PNG, WebP, GIF (max 10 MB).
  ## When disabled, only admins can upload artwork.
  # ND_ENABLEARTWORKUPLOAD: true
  ## Controls whether the player in the UI will animate the album cover (rotation).
  # ND_ENABLECOVERANIMATION: true
  ## Enable the option in the UI to download music/albums/artists/playlists from the server.
  # ND_ENABLEDOWNLOADS: true
  ## Set this to false to completely disable ALL external integrations, including the anonymous data collection and the nice login background images.
  # ND_ENABLEEXTERNALSERVICES: true
  ## Enable toggling “Heart”/“Loved” for songs/albums/artists in the UI (maps to “Star”/“Starred” in Subsonic Clients).
  # ND_ENABLEFAVOURITES: true
  ## Use Gravatar images as the user profile image. Needs the user’s email to be filled.
  # ND_ENABLEGRAVATAR: false
  ## Whether sensitive information (like tokens and passwords) should be redacted (hidden) in the logs.
  # ND_ENABLELOGREDACTING: true
  ## Allow HTTP/HTTPS URLs in M3U #EXTALBUMARTURL directives for playlist artwork. Local file paths are always accepted regardless of this setting.
  # ND_ENABLEM3UEXTERNALALBUMART: false
  ## If set to false, it will return the album CoverArt when a song CoverArt is requested.
  # ND_ENABLEMEDIAFILECOVERART: true
  ## Enable/disable the Now Playing feature that tracks what songs users are currently listening to.
  ## When disabled, the “Now Playing” functionality and admin panel will be unavailable.
  # ND_ENABLENOWPLAYING: true
  ## Enable ReplayGain options in the UI.
  # ND_ENABLEREPLAYGAIN: true
  ## Enable/disable scrobble history.
  # ND_ENABLESCROBBLEHISTORY: true
  ## Enable the Sharing feature. (enabled by default since v0.63.0)
  # ND_ENABLESHARING: true
  ## Enable 5-star ratings in the UI.
  # ND_ENABLESTARRATING: true
  ## Enables transcoding configuration in the UI.
  # ND_ENABLETRANSCODINGCONFIG: false
  ## Enable regular users to edit their details and change their password.
  # ND_ENABLEUSEREDITING: true

  ## Opt-in to WebP encoding for resized artwork. When false (default), Navidrome uses JPEG/PNG (preserving the original source format),
  ## avoiding the WebP WASM encoder overhead that caused slow image processing on low-power hardware in v0.61.0. Set to true to re-enable WebP output.
  # ND_ENABLEWEBPENCODING: false

  ## Exit early on startup if Navidrome is running as root (ignored on Windows).
  # ND_ENFORCENONROOTUSER: false

  ## Comma separated list of IP CIDRs (or when listening on a UNIX socket the special value @) which are allowed to use reverse proxy authentication.
  ## Empty means “deny all”.
  ## Note: This option is unnecessary for most reverse proxy setups, only for authenticating reverse proxies.
  # ND_EXTAUTH_TRUSTEDSOURCES: # Empty
  ## HTTP header containing the username from an authenticating proxy.
  # ND_EXTAUTH_USERHEADER: "Remote-User"
  ## URL to redirect users to after logout when using externalized authentication. Allows completing logout from the external auth provider (SSO, OIDC, etc.)
  # ND_EXTAUTH_LOGOUTURL:
  ## Path to ffmpeg executable. Use it when Navidrome cannot find it, or you want to use a specific version.
  # ND_FFMPEGPATH: # Empty (search in the PATH)

  ## Send basic info to your own Google Analytics account. Must be in the format UA-XXXXXXXX
  # ND_GATRACKINGID: # Empty (disabled)

  ## Allows the X-Frame-Options header value to be set with a custom value. Ex: "SAMEORIGIN"
  # ND_HTTPHEADERS_FRAMEOPTIONS: "DENY"

  ## List of ignored articles when sorting/indexing artists.
  # ND_IGNOREDARTICLES: "The El La Los Las Le Les Os As O A"

  ## Size of image (art work) cache. Set to "0" to disable cache
  # ND_IMAGECACHESIZE: "100MB"

  ## Backlog limit for inspect request throttling.
  # ND_INSPECT_BACKLOGLIMIT: 100
  ## Backlog timeout for inspect request throttling.
  # ND_INSPECT_BACKLOGTIMEOUT: "1m"
  ## Enable/disable inspect endpoints.
  # ND_INSPECT_ENABLED: true
  ## Maximum concurrent inspect requests.
  # ND_INSPECT_MAXREQUESTS: 1

  ## Enable Jukebox mode (play audio on server’s hardware).
  # ND_JUKEBOX_ENABLED: false
  ## By default, Jukebox mode is only available to Admins. Set this option to false to allow any valid user to control it.
  # ND_JUKEBOX_ADMINONLY: true
  ## Device to use for Jukebox mode, if there are multiple Jukebox.Devices entries.
  # ND_JUKEBOX_DEFAULT: # Empty (auto detect)

  ## Set this to false to completely disable Last.fm integration.
  # ND_LASTFM_ENABLED: true
  ## Last.fm API Key.
  # ND_LASTFM_APIKEY: # Empty
  ## Last.fm API Secret.
  # ND_LASTFM_SECRET: # Empty
  ## Two letter-code for language to be used to retrieve biographies from Last.fm.
  # ND_LASTFM_LANGUAGE: "en"
  ## When enabled, only the first artist will be scrobbled for tracks with multiple artists, instead of the display artist or concatenated list.
  # ND_LASTFM_SCROBBLEFIRSTARTISTONLY: false

  ## Set this to override the default ListenBrainz base URL (useful with self-hosted solutions like Maloja*.
  # ND_LISTENBRAINZ_BASEURL: "https://api.listenbrainz.org/1/"
  ## Set this to false to completely disable ListenBrainz integration.
  # ND_LISTENBRAINZ_ENABLED: true

  ## Controls the order and sources for fetching lyrics. Comma-separated list of sources checked in order:
  ## embedded (from tags), file extensions like .lrc, .txt, or any custom extension.
  ## Navidrome will search for lyrics files with the same name as the audio file but with the specified extension
  # ND_LYRICSPRIORITY: ".ttml,.yaml,.yml,.elrc,.lrc,.srt,.txt,embedded"

  ## Minimum similarity score (0-100) for matching similar songs from external sources to local library.
  # ND_MATCHER_FUZZYTHRESHOLD: 85
  ## Bias the fuzzy matcher toward starred/high-rated tracks.
  # ND_MATCHER_PREFERSTARRED: true

  ## Maximum allowed size for uploaded cover art images. Accepts human-readable values like '10MB', '1GB'.
  # ND_MAXIMAGEUPLOADSIZE: 10MB

  ## Set the maximum number of playlists shown in the UI’s sidebar. Note that a very large number can cause UI performance issues.
  # ND_MAXSIDEBARPLAYLISTS: 100

  ## Path to mpv executable. Used for Jukebox mode.
  # ND_MPVPATH: # Empty (search in PATH)

  ## Cmd template used to construct the call of the mpv executable. Used for Jukebox mode.
  # ND_MPVCMDTEMPLATE: "mpv --audio-device=%d --no-audio-display %f --input-ipc-server=%s"

  ## Passphrase used to encrypt passwords in the DB.
  # ND_PASSWORDENCRYPTIONKEY: # -

  ## Set the tag(s) to use as the Album ID.
  # ND_PID_ALBUM: "musicbrainz_albumid|albumartistid,album,albumversion,releasedate"
  ## Set the tag(s) to use as the Track ID.
  # ND_PID_TRACK: "musicbrainz_trackid|albumid,discnumber,tracknumber,title"

  ## Limit where to search for and import playlists from. Can be a list of folders/globs (separated by : (or ; on Windows).
  ## Paths MUST be relative to MusicFolder
  # ND_PLAYLISTSPATH: # Empty (meaning any playlist files in your library will be imported)

  ## Enable the plugin system: https://www.navidrome.org/docs/usage/features/plugins/
  # ND_PLUGINS_ENABLED: true
  ## Folder where your plugins are stored. Place your .ndp files in here.
  # ND_PLUGINS_FOLDER: "<DataFolder>/plugins"
  ## Automatically detect when .ndp files in Plugins.Folder are updated and reload plugins immediately.
  # ND_PLUGINS_AUTORELOAD: false
  ## Log level. Useful for troubleshooting. Possible values: error, warn, info, debug, trace.
  # ND_PLUGINS_LOGLEVEL: # (LogLevel of your Navidrome instance)
  ## Size of the plugin compilation cache.
  # ND_PLUGINS_CACHESIZE: "200MB"

  ## Use Sort_* tags to sort columns in the UI.
  # ND_PREFERSORTTAGS: false

  ## Enable extra endpoint with Prometheus metrics.
  # ND_PROMETHEUS_ENABLED: false
  ## Custom path for Prometheus metrics. Useful for blocking unauthorized metrics requests.
  # ND_PROMETHEUS_METRICSPATH: "/metrics"
  ## Enables Basic Auth protection for Prometheus endpoint. User will be navidrome. Leave empty to disable Basic Auth protection.
  # ND_PROMETHEUS_PASSWORD: # Empty (no password/authentication)

  ## Uses music files’ modification time when sorting by “Recently Added”. Otherwise use import time
  # ND_RECENTLYADDEDBYMODTIME: false

  ## Enable/disable the scanner. Set to false to disable automatic scanning of the music library.
  # #ND_SCANNER_ENABLED: true
  ## Schedule for automatic scans. Use Cron syntax.
  # #ND_SCANNER_SCHEDULE: 0 # (disabled)
  ## Time to wait after a file change is detected before starting a scan. Useful to avoid scanning incomplete files.
  ## Set it to 0 to disable the watcher.
  # ND_SCANNER_WATCHERWAIT: "5s"
  ## Enable/disable scanning the music library on startup. Set to false to disable.
  # ND_SCANNER_SCANONSTARTUP: true
  ## Character string used to join multiple artists in display. Change this if you prefer a different separator between artist names.
  # ND_SCANNER_ARTISTJOINER: " • "
  ## List of artist names that must never be split by tag separators (e.g. "Tyler, The Creator").
  # ND_SCANNER_ARTISTSPLITEXCEPTIONS: # Empty
  ## Whether to follow symbolic links when scanning directories. When enabled, the scanner will traverse symlinked directories
  ## and include their contents in the library. When disabled, symlinked directories are ignored during scanning.
  # ND_SCANNER_FOLLOWSYMLINKS: true
  ## Whether to skip folders whose name starts with a dot when scanning. Set to false to index dot-prefixed folders.
  # ND_SCANNER_IGNOREDOTFOLDERS: true
  ## Controls when missing files, albums, and artists are purged from the database during scans.
  ## Possible values: "never" (default, just mark as missing), "always" (purge after every scan), "full" (purge only after a full scan).
  # ND_SCANNER_PURGEMISSING: "never"

  ## Select the search backend. fts uses FTS5 full-text search with BM25 ranking. legacy uses the previous search implementation.
  # ND_SEARCH_BACKEND: "fts"
  ## Match query strings anywhere in searchable fields, not only in word boundaries. Useful for languages where words are not space separated
  # ND_SEARCH_FULLSTRING: false

  ## How long Navidrome will wait before closing web ui idle sessions
  # #ND_SESSIONTIMEOUT: "48h"

  ## Base URL for shared links. Useful when your server address is not a public (ex: when using Tailscale).
  ## See discussion here: https://github.com/navidrome/navidrome/discussions/3117
  # ND_SHAREURL: # Empty (use server address)

  ## How often to refresh Smart Playlists. Check the smart playlists docs.
  # ND_SMARTPLAYLISTREFRESHDELAY: "5s"

  ## Append the subtitle tag to the song title in all Subsonic API responses.
  # ND_SUBSONIC_APPENDSUBTITLE: true
  ## When Subsonic clients request artist’s albums, include albums where the artist participates (ex: Various Artists compilations).
  # ND_SUBSONIC_ARTISTPARTICIPATIONS: false
  ## Append album version/edition information to album names in Subsonic API responses (e.g., “Album Name (Deluxe Edition)”)
  # ND_SUBSONIC_APPENDALBUMVERSION: true
  ## Set to true to report the real path of the music files in the API. Can be customized individually for each client/player.
  ## This can be a security risk, so it is disabled by default.
  # ND_SUBSONIC_DEFAULTREPORTREALPATH: false
  ## Controls whether the averageRating attribute is included in Subsonic API responses.
  ## When disabled, the average rating across all users is not exposed in API responses, though it is still calculated internally.
  ## Set to false to hide other users’ rating data.
  # ND_SUBSONIC_ENABLEAVERAGERATING: true
  ## List of clients that does not work with the new OpenSubsonic API improvements.
  # ND_SUBSONIC_LEGACYCLIENTS: "DSub"

  ## Path for the TLS certificate file, which should include the signature chain if any.
  # ND_TLSCERT: # Empty (disable TLS)
  ## Path for the TLS key file.
  # ND_TLSKEY: # Empty (disable TLS)

  ## Size of transcoding cache. Set to "0" to disable cache.
  # ND_TRANSCODINGCACHESIZE: "100MB"

  ## Enables transcoding cancellation when a client disconnects during streaming.
  ## When enabled, transcoding processes are stopped if the client closes the connection, saving server resources.
  ## Useful for preventing unnecessary transcoding work when users skip or stop playback.
  # ND_TRANSCODING_ENABLECANCELLATION: false
  ## Maximum number of concurrent transcodes server-wide (0 = unlimited).
  # ND_TRANSCODING_MAXCONCURRENT: 0
  ## Maximum number of concurrent transcodes per user (0 = unlimited).
  # ND_TRANSCODING_MAXCONCURRENTPERUSER: 0

  ## Size (in pixels, 200–1200) of cover art requested by the web UI. It was increased from 300px to 600px in 0.61.0;
  ## now configurable and defaulting to 300px to reduce image encoding load on low-power hardware.
  ## Users on capable hardware can raise it for sharper thumbnails.
  # ND_UICOVERARTSIZE: 300

  ## Change background image used in the Login page.
  # ND_UILOGINBACKGROUNDURL: # random music image from this Unsplash.com collection

  ## How often the UI reports playback progress.
  # ND_UIPLAYBACKREPORTINTERVAL: "1m"

  ## Debounce delay in milliseconds for the search input in the UI. Higher values reduce search requests while typing.
  # ND_UISEARCHDEBOUNCEMS: 200

  ## Add a welcome message to the login screen.
  # ND_UIWELCOMEMESSAGE: # Empty

  ## Set file permissions for Unix Socket File.*
  # ND_UNIXSOCKETPERM: "0660"

Dependencies

This role depends on :

• djuuu.docker_project

Some variables allow integration with:

• djuuu.traefik_docker

Example Playbook

Install Navidrome:

- hosts: all
  gather_facts: true
  gather_subset:
    - "!all"
    - "!min"
    - user_id

  roles:
    - djuuu.navidrome_docker

Scan library:

- hosts: all
  gather_facts: false

  tasks:
    - name: Scan library
      ansible.builtin.include_role: { name: djuuu.navidrome_docker, tasks_from: scan }

ansible-playbook navidrome-scan-library.yml -e full=true

License

Beerware License