Come fare self-hosting di Navidrome nel 2026: mount della musica, scansioni e app Subsonic

Se hai già provato a fare self-hosting di Navidrome, probabilmente conosci questa situazione frustrante: l'interfaccia compare, ma le scansioni non trovano alcun file perché il percorso della musica sull'host è stato montato in modo errato. Ricreare il container risolve raramente un'incoerenza tra URL, stato e dipendenze.

Questa guida usa un unico criterio concreto di completamento: eseguire la scansione di una libreria musicale in sola lettura, verificare metadati e artwork, riprodurre una traccia tramite un client Subsonic e salvare una playlist. Ogni scelta di configurazione viene valutata rispetto a questo criterio, non in base a un badge verde del container.

Esegui il backup dello stato che Navidrome non può ricreare

Definisci il recovery point e il recovery time di Navidrome considerando il database di Navidrome, la cache degli artwork, le playlist e la libreria musicale originale. Monta /data prima del bootstrap, scrivi dati di esempio innocui e sostituisci il container per dimostrare che il percorso è effettivamente persistente. Un volume denominato risolve la persistenza durante i redeploy; non risolve invece una compromissione o la perdita del server.

Prepara un ambiente di ripristino pulito, usa la stessa versione applicativa fissata e verifica che utenti, playlist, cronologia di riproduzione e metadati vengano ripristinati e che lo stesso client Subsonic riproduca una traccia nota. Registra i comandi, le correzioni dei permessi e il tempo trascorso. La guida ai backup offre uno standard utile: un backup è affidabile dopo il ripristino, non dopo l'upload.

Avvia Navidrome senza nascondere i componenti

Usa il container come runtime sostituibile, non come fonte di verità.

docker run -d \
  --name navidrome \
  --restart unless-stopped \
  -p 127.0.0.1:4533:4533 \
  -v navidrome-data:/data \
  -v /srv/music:/music:ro \
  -e ND_BASEURL=/ \
  deluan/navidrome:latest

Verifica il requisito locale prima dell'esposizione: un mount della libreria musicale in sola lettura e dati applicativi scrivibili. Ispeziona l'utente del container, i percorsi scrivibili e il listener in ascolto prima di esporlo. Esegui l'intera operazione — scansionare una libreria musicale in sola lettura, verificare metadati e artwork, riprodurre una traccia tramite un client Subsonic e salvare una playlist — e conserva il riferimento esatto all'immagine che ha prodotto il risultato.

Scegli la topologia minima praticabile per Navidrome

Inizia dal network namespace di Navidrome: il suo web listener usa la porta 4533, non una porta dell'host copiata da un tutorial per laptop. Il requisito del runtime locale è un mount della libreria musicale in sola lettura e dati applicativi scrivibili. Registralo accanto all'immagine e alla porta, così un host sostitutivo riceverà la stessa capacità locale.

Dopo aver soddisfatto il requisito, esegui lo scenario completo — scansionare una libreria musicale in sola lettura, verificare metadati e artwork, riprodurre una traccia tramite un client Subsonic e salvare una playlist. Registra log e misurazioni relativi al tempo di scansione della libreria, all'uso della CPU per il transcoding, alla cache degli artwork, agli stream concorrenti e al throughput del disco. Queste evidenze diventano la prima architettura funzionante nota e rendono verificabili gli spostamenti successivi tra il compute di Dockup e un server collegato.

Il TLS è semplice; gli URL generati no

Imposta ND_BASEURL quando servi il sistema da un sottopercorso; altrimenti preferisci un host HTTPS dedicato. Invia l'hostname scelto alla porta 4533 del container, inoltra l'host originale e lo schema HTTPS ed evita di pubblicare una seconda origin diretta.

Testa Navidrome da un client esterno pulito. Distingui un errore di ingress dal limite applicativo noto — le scansioni non trovano alcun file perché il percorso della musica sull'host è stato montato in modo errato. Un errore di certificato, DNS o 502 appartiene al routing; una richiesta che raggiunge Navidrome e fallisce in seguito appartiene allo stato dell'applicazione, alla capacità o al relativo requisito di supporto. La guida al TLS automatico per domini personalizzati tratta il primo gruppo.

Cinque verifiche più solide dell'health del container

Prima dell'arrivo degli utenti reali, prepara una checklist di release per Navidrome. Deve indicare l'immagine fissata, la porta 4533, l'origin canonica, i percorsi persistenti e il responsabile di un mount della libreria musicale in sola lettura con dati applicativi scrivibili. Allega il risultato atteso di questa transazione: scansionare una libreria musicale in sola lettura, verificare metadati e artwork, riprodurre una traccia tramite un client Subsonic e salvare una playlist.

Usa la checklist dopo una normale sostituzione e dopo un ripristino pulito. Il recovery viene accettato solo se utenti, playlist, cronologia di riproduzione e metadati vengono ripristinati e lo stesso client Subsonic riproduce una traccia nota. Raccogli inoltre una breve traccia delle risorse, comprendente tempo di scansione della libreria, uso della CPU per il transcoding, cache degli artwork, stream concorrenti e throughput del disco; conservala accanto alla release, così le future variazioni di capacità potranno essere confrontate usando lo stesso carico di lavoro.

Includi un errore controllato: invia un input innocuo vicino al limite di risorse o di formato associato a questo confine: le scansioni non trovano alcun file perché il percorso della musica sull'host è stato montato in modo errato. Verifica che Navidrome segnali il problema al confine corretto, ripristina la condizione valida e ripeti la transazione. Questo controlla la visibilità degli errori, non solo il successo, e impedisce che un'interfaccia apparentemente funzionante nasconda un worker, un callback o una connessione al database non funzionante.

Log che rispondono alla domanda successiva

Usa la scansione di una libreria musicale in sola lettura, la verifica di metadati e artwork, la riproduzione di una traccia tramite un client Subsonic e il salvataggio di una playlist come smoke test di Navidrome dopo ogni deployment. Le metriche di supporto sono il tempo di scansione della libreria, l'uso della CPU per il transcoding, la cache degli artwork, gli stream concorrenti e il throughput del disco; configura gli alert nei punti in cui queste risorse si avvicinano a una soglia che degrada l'azione dell'utente.

Il rischio principale di modifica è che le migrazioni del database di Navidrome e il comportamento dello scanner debbano essere testati lasciando intatti i file musicali originali. Una release sicura parte da uno snapshot ripristinabile e convalida qualsiasi modifica di stato unidirezionale prima di spostare il traffico. Quando le scansioni non trovano alcun file perché il percorso della musica sull'host è stato montato in modo errato, mantieni il container fallito abbastanza a lungo da leggerne la configurazione e il primo errore.

Non dare a Navidrome l'intero host

Chiudi la finestra di bootstrap non appena esiste il primo amministratore considerato affidabile. Il problema concreto di Navidrome consiste nel montare la libreria musicale in lettura-scrittura senza una motivazione; il confine più sicuro consiste nel montare la musica in sola lettura, proteggere gli account ed esporre solo il servizio di streaming, non la libreria dell'host.

ND_BASEURL è una configurazione, non un secret; mantieni esplicito il suo valore proteggendo al contempo le credenziali separate utilizzate da Navidrome. La rete privata dovrebbe trasportare le credenziali delle dipendenze e i ruoli interni a Navidrome dovrebbero concedere l'azione utile minima. Mantieni i body sensibili delle richieste e le risposte dei provider fuori dai log ordinari.

Mantieni esplicito Navidrome mentre Dockup gestisce il routing

Routing, certificati, sostituzione dei servizi e storage collegato sono obiettivi ragionevoli per l'automazione. Dockup li gestisce per Navidrome e può eseguire il provisioning del database gestito correlato oppure collegarsi ai servizi presenti sul server del cliente.

Ciò che non dovrebbe inventare è la trust policy di Navidrome. Dopo il deployment, imposta ND_BASEURL quando servi il sistema da un sottopercorso; altrimenti preferisci un host HTTPS dedicato, applica questo confine — monta la musica in sola lettura, proteggi gli account ed esponi solo il servizio di streaming, non la libreria dell'host — e verifica il risultato di questo scenario: scansionare una libreria musicale in sola lettura, verificare metadati e artwork, riprodurre una traccia tramite un client Subsonic e salvare una playlist. Il risultato è un'infrastruttura one-click con un acceptance test specifico per l'applicazione.

Domande frequenti

Di cosa ha bisogno Navidrome per un deployment in produzione?

Instrada il container Navidrome sulla porta 4533 attraverso un'unica origin HTTPS. Il requisito del runtime locale è un mount della libreria musicale in sola lettura e dati applicativi scrivibili. Non considerare Navidrome pronto finché non puoi scansionare una libreria musicale in sola lettura, verificare metadati e artwork, riprodurre una traccia tramite un client Subsonic e salvare una playlist.

Quali dati di Navidrome devono essere inclusi in un backup?

Rendi persistente /data e includi il database di Navidrome, la cache degli artwork, le playlist e la libreria musicale originale nello stesso manifest di recovery. Un ripristino pulito di Navidrome è riuscito solo quando utenti, playlist, cronologia di riproduzione e metadati vengono ripristinati e lo stesso client Subsonic riproduce una traccia nota.

Navidrome richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origin pubblica di Navidrome e mantieni la porta 4533 sul percorso interno. Applica correttamente l'impostazione di Navidrome: imposta ND_BASEURL quando servi il sistema da un sottopercorso; altrimenti preferisci un host HTTPS dedicato. Per Navidrome, HTTPS protegge le credenziali o i contenuti degli utenti durante il transito e mantiene coerente il comportamento dei client sensibile all'origin.

Come va testato un upgrade di Navidrome?

Ripristina lo stato corrente di Navidrome in un deployment isolato, applica la versione candidata e ripeti la relativa transazione di accettazione. Presta particolare attenzione perché le migrazioni del database di Navidrome e il comportamento dello scanner devono essere testati lasciando intatti i file musicali originali. Mantieni l'immagine precedente di Navidrome finché non avrai compreso i confini della migrazione dei dati e del rollback.