Navidrome zelf hosten in 2026: muziekmounts, scans en Subsonic-apps

Als je al eens hebt geprobeerd om Navidrome zelf te hosten, herken je deze frustrerende situatie waarschijnlijk: de UI verschijnt, maar scans vinden geen bestanden omdat het muziekpad op de host verkeerd is gemount. De container opnieuw aanmaken lost een verschil tussen URL's, state en dependencies zelden op.

In deze walkthrough gebruiken we één concreet voltooiingscriterium: een read-only muziekbibliotheek scannen, metadata en artwork controleren, een track streamen via een Subsonic-client en een playlist opslaan. Elke configuratiekeuze wordt aan dat criterium getoetst, niet aan een groen containerbadge.

Maak een back-up van de state die Navidrome niet kan reconstrueren

Bepaal het recovery point en de recovery time voor Navidrome aan de hand van de Navidrome-database, artwork-cache, playlists en de oorspronkelijke muziekbibliotheek. Mount /data vóór de bootstrap, schrijf onschadelijke voorbeelddata en vervang de container om te bewijzen dat het pad daadwerkelijk persistent is. Een named volume zorgt voor persistence bij redeployments, maar lost een compromise of serververlies niet op.

Bouw een schone restore-omgeving, gebruik dezelfde gepinde applicatieversie en bewijs dat gebruikers, playlists, afspeelgeschiedenis en metadata terugkomen en dat dezelfde Subsonic-client een bekende track kan streamen. Leg commando's, wijzigingen aan ownership en de verstreken tijd vast. De back-uphandleiding is een nuttige standaard: een back-up is pas betrouwbaar na een restore, niet na een upload.

Start Navidrome zonder de bewegende delen te verbergen

Gebruik de container als een vervangbare runtime, niet als de bron van waarheid.

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

Controleer de lokale vereiste voordat je Navidrome extern beschikbaar maakt: een read-only mount van de muziekbibliotheek plus schrijfbare applicatiedata. Inspecteer de containergebruiker, schrijfbare paden en gebonden listener voordat je de service blootstelt. Voer de volledige actie uit — een read-only muziekbibliotheek scannen, metadata en artwork controleren, een track streamen via een Subsonic-client en een playlist opslaan — en bewaar de exacte image-referentie die het resultaat heeft opgeleverd.

Kies de kleinst haalbare Navidrome-topologie

Begin met de network namespace van Navidrome: de weblistener gebruikt poort 4533, niet een hostpoort die je uit een laptop-tutorial hebt overgenomen. De lokale runtimevereiste is een read-only mount van de muziekbibliotheek plus schrijfbare applicatiedata. Leg dit naast de image en poort vast, zodat een vervangende host dezelfde lokale capability krijgt.

Nadat aan de vereiste is voldaan, voer je het volledige scenario uit — een read-only muziekbibliotheek scannen, metadata en artwork controleren, een track streamen via een Subsonic-client en een playlist opslaan. Leg logs en metingen vast voor de scantijd van de bibliotheek, CPU-gebruik voor transcoding, de artwork-cache, gelijktijdige streams en disk throughput. Die gegevens vormen de eerste known-good-architectuur en maken latere verplaatsingen tussen Dockup compute en een aangesloten server testbaar.

TLS is eenvoudig; gegenereerde URL's niet

Stel ND_BASEURL in wanneer je Navidrome vanuit een subpad serveert; kies anders bij voorkeur een dedicated HTTPS-host. Stuur de gekozen hostnaam door naar containerpoort 4533, stuur de oorspronkelijke host en het HTTPS-schema door en publiceer geen tweede directe origin.

Test Navidrome vanuit een schone externe client. Maak onderscheid tussen een ingress-probleem en de bekende applicatiegrens — scans vinden geen bestanden omdat het muziekpad op de host verkeerd is gemount. Een certificaat-, DNS- of 502-fout hoort bij routing; een request dat Navidrome bereikt en daarna faalt, hoort bij applicatiestate, capaciteit of een ondersteunende vereiste. De handleiding voor TLS met een custom domain behandelt de eerste groep.

Vijf controles die sterker zijn dan container health

Maak voordat de eerste echte gebruikers arriveren een releasewerkblad voor Navidrome. Daarin moeten de gepinde image, poort 4533, canonical origin, persistente paden en de eigenaar van een read-only mount van de muziekbibliotheek plus schrijfbare applicatiedata staan. Voeg het verwachte resultaat van deze transactie toe: een read-only muziekbibliotheek scannen, metadata en artwork controleren, een track streamen via een Subsonic-client en een playlist opslaan.

Gebruik het werkblad na een normale vervanging en na een schone restore. Recovery wordt alleen geaccepteerd als gebruikers, playlists, afspeelgeschiedenis en metadata terugkomen en dezelfde Subsonic-client een bekende track kan streamen. Verzamel ook een korte resource trace met de scantijd van de bibliotheek, CPU-gebruik voor transcoding, de artwork-cache, gelijktijdige streams en disk throughput; bewaar die naast de release, zodat toekomstige capaciteitswijzigingen met dezelfde workload worden vergeleken.

Voeg één gecontroleerde fout toe: dien onschadelijke input in rond de resource- of formatlimiet die bij deze grens hoort: scans vinden geen bestanden omdat het muziekpad op de host verkeerd is gemount. Controleer of Navidrome het probleem op de juiste grens rapporteert, herstel de geldige toestand en voer de transactie opnieuw uit. Hiermee controleer je de zichtbaarheid van fouten, niet alleen succes, en voorkom je dat een gezond ogende interface een defecte worker, callback of databaseverbinding verbergt.

Logs die de volgende vraag beantwoorden

Gebruik het scannen van een read-only muziekbibliotheek, het controleren van metadata en artwork, het streamen van een track via een Subsonic-client en het opslaan van een playlist als Navidrome-smoketest na elke deployment. De bijbehorende metrics zijn de scantijd van de bibliotheek, CPU-gebruik voor transcoding, de artwork-cache, gelijktijdige streams en disk throughput; stel alerts in wanneer deze resources een punt naderen waarop de gebruikersactie verslechtert.

Het grootste changerisico is dat Navidrome-databasemigraties en scanner gedrag moeten worden getest terwijl de oorspronkelijke muziekbestanden onaangeroerd blijven. Een veilige release begint met een restorebare snapshot en valideert elke eenmalige statewijziging voordat het verkeer wordt omgeleid. Wanneer scans geen bestanden vinden omdat het muziekpad op de host verkeerd is gemount, houd je de mislukte container lang genoeg in stand om de configuratie en de eerste fout te lezen.

Geef Navidrome niet de volledige host

Sluit het bootstrapvenster zodra de eerste vertrouwde administrator bestaat. De concrete valkuil bij Navidrome is dat je de muziekbibliotheek zonder reden read-write mount; de veiligere grens is om muziek read-only te mounten, accounts te beschermen en alleen de streamingservice bloot te stellen, niet de bibliotheek op de host.

ND_BASEURL is configuratie en geen secret; houd de waarde expliciet en bescherm tegelijk de afzonderlijke credentials die Navidrome gebruikt. Gebruik private networking voor dependency-credentials en laat rollen binnen Navidrome alleen de kleinst nuttige actie uitvoeren. Zorg dat gevoelige request bodies en responses van providers niet in routinematige logs terechtkomen.

Houd Navidrome expliciet terwijl Dockup de routing afhandelt

Routing, certificaten, servicevervanging en attached storage zijn redelijke doelen voor automation. Dockup handelt die zaken voor Navidrome af en kan de bijbehorende managed database provisionen of verbinding maken met services op de eigen server van een klant.

Wat het niet moet invullen, is het trustbeleid van Navidrome. Stel na de deployment ND_BASEURL in wanneer je vanuit een subpad serveert; kies anders bij voorkeur een dedicated HTTPS-host, handhaaf deze grens — mount muziek read-only, bescherm accounts en stel alleen de streamingservice bloot, niet de bibliotheek op de host — en controleer het resultaat van dit scenario: een read-only muziekbibliotheek scannen, metadata en artwork controleren, een track streamen via een Subsonic-client en een playlist opslaan. Het resultaat is infrastructuur met één klik en een applicatiespecifieke acceptatietest.

Veelgestelde vragen

Wat heeft Navidrome nodig voor een production deployment?

Routeer de Navidrome-container op poort 4533 via één HTTPS-origin. De lokale runtimevereiste is een read-only mount van de muziekbibliotheek plus schrijfbare applicatiedata. Noem Navidrome pas gereed als je een read-only muziekbibliotheek kunt scannen, metadata en artwork kunt controleren, een track kunt streamen via een Subsonic-client en een playlist kunt opslaan.

Welke Navidrome-data hoort in een back-up?

Maak /data persistent en neem de Navidrome-database, artwork-cache, playlists en de oorspronkelijke muziekbibliotheek op in hetzelfde recoverymanifest. Een schone Navidrome-restore is pas geslaagd wanneer gebruikers, playlists, afspeelgeschiedenis en metadata terugkomen en dezelfde Subsonic-client een bekende track kan streamen.

Heeft Navidrome HTTPS nodig achter een reverse proxy?

Gebruik HTTPS voor de publieke Navidrome-origin en houd poort 4533 op de interne route. Pas de Navidrome-instelling correct toe: stel ND_BASEURL in wanneer je vanuit een subpad serveert; kies anders bij voorkeur een dedicated HTTPS-host. Voor Navidrome beschermt HTTPS credentials of gebruikerscontent tijdens transport en zorgt het ervoor dat origingevoelig clientgedrag consistent blijft.

Hoe moet een Navidrome-upgrade worden getest?

Restore de huidige Navidrome-state naar een geïsoleerde deployment, pas de kandidaatversie toe en herhaal de acceptatietransactie. Let hier extra op, omdat Navidrome-databasemigraties en scanner gedrag moeten worden getest terwijl de oorspronkelijke muziekbestanden onaangeroerd blijven. Bewaar de vorige Navidrome-image totdat de grenzen van datamigratie en rollback duidelijk zijn.