Vai al contenuto

Navidrome Docker: come installare il server musicale di casa

Illustrazione 3D di una stanza con un server musicale casalingo e streaming verso uno smartphone.
Immagine generata con IA

Chi conserva la propria musica in una cartella di file MP3 o FLAC può farla diventare una libreria da ascoltare in tutta la casa con Navidrome, un server musicale open source. Navidrome legge quella cartella, ordina i brani per album e artisti in base ai tag e li offre in due modi: con un’interfaccia web e con l’API Subsonic, cioè quella usata dalle app per telefono e computer. Il percorso descritto qui usa l’immagine Docker ufficiale con docker-compose. Si parte dai permessi delle due cartelle che il container usa, si passa per il file docker-compose.yml, l’utente amministratore e le poche opzioni utili all’inizio, e si arriva al primo brano riprodotto nella rete di casa. I comandi sono quelli della documentazione ufficiale, elencata in fondo.

Cosa serve

  • Un sistema Linux con Docker e Compose. La pagina Docker di Navidrome usa soltanto comandi e percorsi in stile Linux, e questa guida la segue. Docker Desktop su Windows e macOS fa girare la stessa immagine, ma le pagine consultate non dicono come scrivere su quei sistemi i percorsi delle cartelle, quindi la guida non li indica.
  • Compose nella forma giusta. La pagina Docker usa l’eseguibile autonomo docker-compose. Chi ha Compose come plugin di Docker scrive gli stessi comandi come docker compose, con lo spazio: per esempio docker compose up -d al posto di docker-compose up -d.
  • Una delle piattaforme per cui l’immagine è pubblicata: linux/amd64, linux/arm/v6, linux/arm/v7 e linux/arm64.
  • La musica raccolta in una cartella. Fra i formati supportati la pagina Getting Started cita MP3, FLAC, AAC, OGG, OPUS, WMA, APE e WavPack, e chiede che i file abbiano metadati audio (tag) corretti.
  • Una seconda cartella per i dati di Navidrome, dove il programma crea il database e la cache.
  • La porta 4533, quella predefinita, raggiungibile dagli altri dispositivi della rete.

1. Preparare la cartella dei dati e trovare UID e GID

Il container gira con l’utente scritto nella direttiva user del compose, e quell’utente deve poter leggere e scrivere in /data, dove nascono database e cache. La cartella dei dati sul computer deve quindi appartenergli, e per assegnargliela servono i numeri del proprio account. Il primo comando stampa l’UID:

id -u

Il secondo stampa il GID:

id -g

I due numeri vanno annotati perché finiranno nel compose: la documentazione avverte che gli ID degli esempi non coincidono per forza con quelli della propria macchina. Poi si crea la cartella dei dati:

mkdir -p /path/to/data

Al posto di /path/to/data va scritto il percorso scelto per i dati. Deve essere un percorso assoluto, perché la documentazione chiede percorsi assoluti e non relativi.

Attenzione: il comando che segue cambia il proprietario della cartella indicata e di tutto ciò che contiene, sottocartelle comprese. Prima di premere Invio si rilegge il percorso, che deve essere esattamente quello appena creato con mkdir. Se per errore si indica la propria home, una cartella condivisa o una cartella di sistema, tutti quei file passano al proprio utente, e i programmi che si aspettavano un altro proprietario possono smettere di funzionare.

sudo chown -R $(id -u):$(id -g) /path/to/data

La parte $(id -u):$(id -g) inserisce da sola i due numeri visti sopra; /path/to/data va sostituito con lo stesso percorso usato con mkdir.

2. Controllare che Navidrome possa leggere la musica

Sulla libreria a Navidrome basta la lettura: non deve scriverci, e del resto, come spiegano le FAQ del progetto, per scelta di progetto non modifica mai i file né la cartella della musica. Per vedere proprietari e permessi ci si sposta da terminale nella cartella della musica e si lancia:

ls -n

Con -n proprietario e gruppo compaiono come numeri, così che il confronto con l’UID e il GID annotati sia immediato. Il comando, lanciato dentro la cartella, mostra file e sottocartelle che contiene, non la cartella stessa. Che i numeri coincidano non basta, dato che la proprietà da sola non garantisce l’accesso: nella colonna dei permessi bisogna verificare che l’utente del container abbia la lettura sui file e il permesso di esecuzione, cioè di attraversamento, su ogni cartella della libreria. La pagina Docker parla infatti di accesso in lettura ed esecuzione.

Se i proprietari sono altri o i permessi mancano, la pagina Docker indica due strade:

  • cambiare il proprietario della cartella musica con chown, come per la cartella dei dati;
  • se la cartella è usata anche da altri programmi, aprirla in lettura a tutti con chmod.

Qui si segue la seconda, che lascia intatti i proprietari dei file ed è quella da prendere quando la musica appartiene a un altro utente.

Attenzione: il comando che segue modifica in blocco i permessi di tutti i file e le sottocartelle del percorso indicato, dando a ogni account della macchina la lettura dei file e l’attraversamento delle cartelle. Con un percorso sbagliato si rendono leggibili file che dovevano restare privati. Al posto di /path/to/your/music/folder va scritto il percorso assoluto della cartella musica, lo stesso che poi si metterà nei volumi del compose.

sudo chmod -R a+rX /path/to/your/music/folder

La X maiuscola aggiunge l’esecuzione alle cartelle, e cioè proprio il permesso di attraversamento.

3. Scrivere il file docker-compose.yml

Si crea una cartella per il progetto e al suo interno un file docker-compose.yml, in cui va copiato per intero il blocco Using docker-compose della pagina Docker ufficiale, che definisce un servizio navidrome. Tre righe lo caratterizzano. La prima indica l’immagine:

image: navidrome/navidrome:latest

La seconda l’utente con cui gira il container:

user: 1000:1000

Qui 1000:1000 va sostituito con l’UID e il GID trovati al passaggio 1, nella forma UID:GID, perché devono essere gli stessi numeri usati nei comandi sui permessi. La terza è la politica di riavvio dell’esempio ufficiale:

restart: unless-stopped

Nello stesso blocco ci sono poi le righe da adattare:

  • sotto ports, la porta 4533 del computer è collegata alla 4533 del container;
  • sotto volumes, la cartella dei dati è montata su /data: nell’esempio è /path/to/data, e si cambia solo la parte a sinistra dei due punti;
  • sempre sotto volumes, la cartella musica è montata su /music con il suffisso :ro, cioè in sola lettura; anche qui si cambia solo il percorso a sinistra.

La sezione environment dell’esempio contiene solo commenti, e la documentazione precisa che quelle variabili non sono obbligatorie. Le variabili PUID e PGID, diffuse in molte guide, non vanno aggiunte: sono una convenzione delle immagini linuxserver.io e l’immagine di Navidrome le ignora, perché l’utente si sceglie soltanto con user. Le pagine consultate non descrivono una procedura per aggiornare l’immagine.

4. Avviare il servizio

Dalla cartella che contiene docker-compose.yml si avvia il servizio in background con il comando della pagina Docker:

docker-compose up -d

Chi usa Compose come plugin scrive invece docker compose up -d; lo stesso vale per tutti i comandi Compose citati più avanti.

5. Controllare nei log che l’avvio sia riuscito

La pagina Getting Started chiede di verificare che Navidrome sia partito prima di creare l’amministratore. Con il compose non serve conoscere il nome del container: le FAQ indicano docker-compose logs, e dalla cartella del progetto si usa docker-compose logs navidrome, e docker-compose logs -f navidrome per seguire i messaggi man mano che arrivano (con il plugin, docker compose logs navidrome e docker compose logs -f navidrome). navidrome è il nome del servizio scritto nel file.

Chi ha avviato il container con il comando docker run della pagina Docker, che usa l’opzione --name navidrome, legge invece i log con i comandi di Getting Started:

docker logs navidrome

E per seguirli in tempo reale:

docker logs -f navidrome

In un avvio riuscito compaiono la creazione del database, l’inizio della scansione e il messaggio che il server è pronto, con righe come queste:

Creating DB Schema
Scanner: Starting scan
Navidrome server is ready!

Se invece compaiono errori su cartelle mancanti o permessi negati, prima di proseguire conviene leggere la sezione sui problemi in fondo.

6. Creare l’utente amministratore al primo accesso

Nel browser si apre http://localhost:4533; da un altro dispositivo della rete di casa si usa, al posto di localhost, l’indirizzo IP del computer che ospita Navidrome. Compare la schermata di creazione dell’amministratore: si inseriscono nome utente e password, si ripete la password e si preme Create Admin.

Si entra subito nell’interfaccia, con le voci Albums, Artists e Playlists nella barra laterale. Il passaggio non va rimandato, perché Navidrome importa le playlist .m3u presenti nella cartella musica solo dopo che esiste un amministratore.

7. Attendere la scansione e controllare i tag

La scansione avviene da sola in background e album e artisti compaiono man mano: per ascoltare non serve aspettare. Getting Started indica questi tempi approssimativi:

Dimensione della libreria Tempo di scansione approssimativo
meno di 1.000 brani meno di 1 minuto
1.000 – 10.000 brani 1-5 minuti
10.000 – 50.000 brani 5-15 minuti
oltre 50.000 brani oltre 15 minuti

Che album e artisti appaiano in ordine dipende dai tag, perché Navidrome organizza la musica soltanto in base a quelli e non deduce un album dalla cartella in cui stanno i file. Le FAQ fanno due esempi: in una raccolta di artisti vari tutti i brani devono avere il tag di compilation (TCMP=1 per ID3, COMPILATION=1 per FLAC), mentre in un album di un solo artista con ospiti diversi l’Album Artist deve essere identico su ogni traccia. Per sistemare i tag il progetto rimanda alle proprie Tagging Guidelines e a editor esterni come beets e MusicBrainz Picard.

Se la musica non compare affatto, si ricontrolla il percorso a sinistra del volume /music, ricordando che su Linux e macOS i percorsi distinguono tra maiuscole e minuscole.

8. Regolare le opzioni principali con le variabili ND_

Per Docker la documentazione usa le variabili d’ambiente, da scrivere nella sezione environment del compose: il nome di ogni opzione prende il prefisso ND_ ed è tutto in maiuscolo. Esiste anche un file navidrome.toml nella cartella /data, ma qui si resta sulle variabili per non mescolare le due forme; se la stessa opzione è impostata in entrambi i modi, la variabile d’ambiente ha la precedenza. Fra le opzioni di configurazione, all’inizio contano queste:

  • ND_SCANNER_SCHEDULE: la scansione programmata, in sintassi cron. Il valore predefinito è 0, cioè disattivata.
  • ND_SCANNER_WATCHERWAIT: quanto attendere, dopo che è stata rilevata la modifica di un file, prima di avviare la scansione, così da non leggere file ancora incompleti. Il predefinito è 5s; 0 disattiva il controllo delle modifiche.
  • ND_PORT: la porta HTTP, predefinita 4533, la stessa della riga ports dell’esempio. La pagina Docker non tratta il caso in cui la si cambi.
  • ND_DATAFOLDER e ND_MUSICFOLDER: con Docker restano /data e /music, e per spostare dati o musica si cambia il percorso a sinistra nei volumi.
  • ND_LOGLEVEL: il livello dei log, predefinito info, con i valori error, warn, info, debug e trace.

Ogni opzione va su una riga sotto environment, come la riga commentata con ND_LOGLEVEL dell’esempio ufficiale. Dopo ogni modifica si rilancia docker-compose up -d (o docker compose up -d) dalla stessa cartella, come al passaggio 4.

9. Ascoltare dal browser o da un’app Subsonic

Dal browser si apre Albums nella barra laterale, si sceglie una copertina e si preme play su un brano. Da telefono o computer si usa invece un client: secondo la pagina delle app, con Navidrome funziona qualunque app che supporti l’API OpenSubsonic. Alcuni client dell’elenco ufficiale, in ordine alfabetico:

  • Amperfy, per iOS, iPadOS e macOS;
  • iSub, per iPhone e iPad;
  • Substreamer, per iOS e Android;
  • Symfonium, per Android;
  • Ultrasonic, per Android.

Nell’app si indica come server http://IP-del-computer:4533, con il nome utente e la password creati al passaggio 6. L’accesso da fuori casa e HTTPS richiedono configurazioni separate, trattate in altre guide.

Se qualcosa va storto

I messaggi citati qui sotto si leggono con i comandi del passaggio 5: docker-compose logs navidrome (o docker compose logs navidrome) per chi usa il compose, docker logs navidrome per chi ha usato docker run.

Navidrome non parte e la pagina non si apre

Quando la cartella dei dati non è scrivibile, Navidrome non riesce a creare il database e il container si ferma all’avvio. Nei log compare un errore che contiene unable to open database file: no such file or directory, seguito da un panic. Si rimedia ripetendo il passaggio 1: la cartella dei dati deve esistere e appartenere all’UID e al GID scritti in user.

L’interfaccia si apre ma la libreria resta vuota

La prima cosa da considerare è la scansione, che su librerie grandi richiede tempo: se nei log continua l’attività di scansione, basta aspettare. Se la libreria resta vuota anche dopo, la documentazione indica tre cause:

  • l’utente del container non può leggere i file o attraversare le cartelle della musica: si rimedia con il passaggio 2;
  • il percorso a sinistra del volume /music non corrisponde a quello reale, maiuscole e minuscole comprese;
  • i file non hanno tag corretti.

Nel caso dei permessi, nei log compaiono errori permission denied su /music e un avviso secondo cui la cartella non esisterebbe. La cartella esiste: è l’utente del container che non riesce ad aprirla. Togliere la direttiva user fa sparire l’errore solo perché il container gira allora come root, che può scrivere ovunque; la documentazione lo sconsiglia in produzione e indica di correggere i proprietari delle cartelle.

Il browser non raggiunge Navidrome

Prima si verifica nei log, con i comandi del passaggio 5, che il servizio sia partito. Poi si controllano tre cose:

  • l’indirizzo è http://localhost:4533 sul computer stesso, oppure l’IP del server dagli altri dispositivi;
  • la mappatura nel compose deve essere 4533:4533, o quella della porta personalizzata;
  • nel firewall la porta deve essere aperta.

Le playlist non vengono importate

Le playlist .m3u vengono importate solo se l’amministratore esiste già, e una playlist scartata prima non viene ripresa da sola. Dopo aver creato l’amministratore si aggiorna la data di modifica dei file con touch /path/to/music/*.m3u, sostituendo /path/to/music con il percorso reale, sul computer, della cartella che contiene i file .m3u. Poi si avvia una scansione manuale dall’interfaccia, oppure si attende il ciclo di scansione successivo.

Documentazione di riferimento

Pagine ufficiali consultate il 19 novembre 2026:

Leggi anche

  • Docker
  • Docker Compose
  • Navidrome
  • Subsonic