Comment auto-héberger Navidrome en 2026 : montages de musique, scans et applications Subsonic

Si vous avez déjà essayé d’auto-héberger Navidrome, vous connaissez probablement cette situation frustrante : l’interface s’affiche, mais les scans ne trouvent aucun fichier parce que le chemin de la musique sur l’hôte est mal monté. Recréer le conteneur ne corrige généralement pas un désaccord entre les URL, l’état et les dépendances.

Cette procédure repose sur un critère de validation concret : analyser une bibliothèque musicale montée en lecture seule, vérifier les métadonnées et les pochettes, diffuser un morceau via un client Subsonic et enregistrer une playlist. Chaque choix de configuration est évalué au regard de ce critère, plutôt qu’à partir d’un simple indicateur de conteneur en état « healthy ».

Sauvegarder l’état que Navidrome ne peut pas recréer

Définissez le point et le délai de reprise de Navidrome en tenant compte de la base de données Navidrome, du cache des pochettes, des playlists et de la bibliothèque musicale d’origine. Montez /data avant l’initialisation, écrivez quelques données de test inoffensives, puis remplacez le conteneur pour vérifier que ce chemin est réellement persistant. Un named volume garantit la persistance lors d’un redeploy ; il ne protège ni contre une compromission ni contre la perte du serveur.

Préparez un environnement de restauration propre, utilisez la même version applicative épinglée et vérifiez que les utilisateurs, les playlists, l’historique de lecture et les métadonnées sont restaurés, puis que le même client Subsonic diffuse un morceau connu. Consignez les commandes, les corrections de propriété et le temps écoulé. Le guide des sauvegardes constitue une bonne référence : une sauvegarde est fiable après sa restauration, pas après son upload.

Démarrer Navidrome sans masquer les éléments importants

Utilisez le conteneur comme un runtime remplaçable, et non comme la source de vérité.

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

Vérifiez la condition locale avant toute exposition : un montage de bibliothèque musicale en lecture seule, ainsi que des données applicatives accessibles en écriture. Inspectez l’utilisateur du conteneur, les chemins accessibles en écriture et le listener lié avant de l’exposer. Exécutez le parcours complet — analyser une bibliothèque musicale montée en lecture seule, vérifier les métadonnées et les pochettes, diffuser un morceau via un client Subsonic et enregistrer une playlist — puis conservez la référence exacte de l’image ayant produit ce résultat.

Choisir la topologie Navidrome viable la plus simple

Commencez par l’espace de noms réseau de Navidrome : son listener web utilise le port 4533, et non un port hôte copié depuis un tutoriel destiné à un ordinateur portable. La condition d’exécution locale est un montage de bibliothèque musicale en lecture seule, accompagné de données applicatives accessibles en écriture. Consignez-la avec l’image et le port afin qu’un hôte de remplacement dispose des mêmes capacités locales.

Une fois cette condition satisfaite, exécutez le scénario complet — analyser une bibliothèque musicale montée en lecture seule, vérifier les métadonnées et les pochettes, diffuser un morceau via un client Subsonic et enregistrer une playlist. Consignez les logs et les mesures concernant la durée du scan de la bibliothèque, le CPU utilisé par le transcodage, le cache des pochettes, le nombre de flux simultanés et le débit disque. Ces éléments constituent la première architecture de référence fonctionnelle et rendent testables les migrations ultérieures entre le compute Dockup et un serveur attaché.

Le TLS est simple ; les URL générées le sont moins

Définissez ND_BASEURL si le service est accessible depuis un sous-chemin ; sinon, préférez un hôte HTTPS dédié. Faites pointer le nom d’hôte choisi vers le port 4533 du conteneur, transmettez l’hôte d’origine et le schéma HTTPS, et évitez de publier un second origin direct.

Testez Navidrome depuis un client externe vierge. Distinguez les erreurs d’ingress de la limite applicative connue — les scans ne trouvent aucun fichier parce que le chemin de la musique sur l’hôte est mal monté. Une erreur de certificat, de DNS ou de 502 relève du routage ; une requête qui atteint Navidrome puis échoue concerne l’état de l’application, sa capacité ou l’une de ses dépendances. Le guide TLS avec domaine personnalisé couvre le premier groupe.

Cinq vérifications plus fiables que l’état du conteneur

Avant l’arrivée des vrais utilisateurs, créez une fiche de mise en production pour Navidrome. Elle doit indiquer l’image épinglée, le port 4533, l’origin canonique, les chemins persistants et le responsable d’un montage de bibliothèque musicale en lecture seule avec des données applicatives accessibles en écriture. Ajoutez le résultat attendu de cette transaction : analyser une bibliothèque musicale montée en lecture seule, vérifier les métadonnées et les pochettes, diffuser un morceau via un client Subsonic et enregistrer une playlist.

Utilisez cette fiche après un remplacement normal et après une restauration propre. La reprise n’est validée que si les utilisateurs, les playlists, l’historique de lecture et les métadonnées sont restaurés et que le même client Subsonic diffuse un morceau connu. Collectez également une courte trace des ressources couvrant la durée du scan de la bibliothèque, le CPU utilisé par le transcodage, le cache des pochettes, le nombre de flux simultanés et le débit disque ; conservez-la avec la release afin que les futures évolutions de capacité soient comparées avec la même charge.

Incluez un échec contrôlé : envoyez une entrée inoffensive proche de la limite de ressource ou de format associée à cette limite : les scans ne trouvent aucun fichier parce que le chemin de la musique sur l’hôte est mal monté. Vérifiez que Navidrome signale le problème au bon niveau, rétablissez la condition valide, puis relancez la transaction. Cela vérifie la visibilité des erreurs, et pas uniquement la réussite, et empêche une interface apparemment saine de dissimuler un worker, un callback ou une connexion à la base de données défaillant.

Des logs qui répondent à la question suivante

Utilisez « analyser une bibliothèque musicale montée en lecture seule, vérifier les métadonnées et les pochettes, diffuser un morceau via un client Subsonic et enregistrer une playlist » comme smoke test Navidrome après chaque déploiement. Les métriques associées sont la durée du scan de la bibliothèque, le CPU utilisé par le transcodage, le cache des pochettes, le nombre de flux simultanés et le débit disque ; déclenchez les alertes lorsque ces ressources approchent un niveau susceptible de dégrader l’action utilisateur.

Le principal risque lors d’une modification vient du fait que les migrations de la base de données Navidrome et le comportement du scanner doivent être testés alors que les fichiers musicaux d’origine restent intacts. Une release sûre commence par un snapshot restaurable et valide toute modification d’état irréversible avant de transférer le trafic. Lorsque les scans ne trouvent aucun fichier parce que le chemin de la musique sur l’hôte est mal monté, conservez suffisamment longtemps le conteneur défaillant pour lire sa configuration et sa première erreur.

Ne donnez pas à Navidrome accès à tout l’hôte

Fermez la fenêtre d’initialisation dès qu’un premier administrateur de confiance existe. Le piège concret de Navidrome consiste à monter la bibliothèque musicale en lecture-écriture sans raison ; la limite la plus sûre est de monter la musique en lecture seule, de protéger les comptes et d’exposer uniquement le service de streaming, plutôt que la bibliothèque de l’hôte.

ND_BASEURL est une configuration, pas un secret ; gardez sa valeur explicite tout en protégeant les identifiants distincts utilisés par Navidrome. Le réseau privé doit transporter les identifiants des dépendances, et les rôles dans Navidrome doivent accorder uniquement l’action utile la plus restreinte. Excluez des logs courants les corps de requête sensibles et les réponses des fournisseurs.

Garder Navidrome explicite tandis que Dockup gère le routage

Le routage, les certificats, le remplacement des services et le stockage attaché sont de bonnes cibles pour l’automatisation. Dockup les prend en charge pour Navidrome et peut provisionner la base de données managée associée ou se connecter à des services hébergés sur le serveur d’un client.

Ce que Dockup ne doit pas inventer, c’est la trust policy de Navidrome. Après le déploiement, définissez ND_BASEURL si le service est accessible depuis un sous-chemin ; sinon, préférez un hôte HTTPS dédié, appliquez cette limite — montez la musique en lecture seule, protégez les comptes et exposez uniquement le service de streaming, plutôt que la bibliothèque de l’hôte — puis vérifiez le résultat de ce scénario : analyser une bibliothèque musicale montée en lecture seule, vérifier les métadonnées et les pochettes, diffuser un morceau via un client Subsonic et enregistrer une playlist. Vous obtenez ainsi une infrastructure déployable en un clic avec un test de validation propre à l’application.

Foire aux questions

De quoi Navidrome a-t-il besoin pour un déploiement en production ?

Faites passer le conteneur Navidrome sur le port 4533 via un unique origin HTTPS. La condition d’exécution locale est un montage de bibliothèque musicale en lecture seule, accompagné de données applicatives accessibles en écriture. Ne considérez pas Navidrome comme prêt tant que vous ne pouvez pas analyser une bibliothèque musicale montée en lecture seule, vérifier les métadonnées et les pochettes, diffuser un morceau via un client Subsonic et enregistrer une playlist.

Quelles données Navidrome doivent figurer dans une sauvegarde ?

Rendez /data persistant et incluez la base de données Navidrome, le cache des pochettes, les playlists et la bibliothèque musicale d’origine dans le même manifeste de reprise. Une restauration propre de Navidrome n’est réussie que lorsque les utilisateurs, les playlists, l’historique de lecture et les métadonnées sont restaurés et que le même client Subsonic diffuse un morceau connu.

Navidrome a-t-il besoin de HTTPS derrière un reverse proxy ?

Utilisez HTTPS pour l’origin Navidrome public et gardez le port 4533 sur le routage interne. Appliquez correctement le paramètre Navidrome : définissez ND_BASEURL si le service est accessible depuis un sous-chemin ; sinon, préférez un hôte HTTPS dédié. Pour Navidrome, HTTPS protège les identifiants ou le contenu utilisateur pendant leur transmission et garantit un comportement cohérent des clients dépendant de l’origin.

Comment tester une mise à niveau de Navidrome ?

Restaurez l’état actuel de Navidrome dans un déploiement isolé, appliquez la version candidate et répétez sa transaction de validation. Soyez particulièrement attentif, car les migrations de la base de données Navidrome et le comportement du scanner doivent être testés alors que les fichiers musicaux d’origine restent intacts. Conservez l’image Navidrome précédente jusqu’à ce que les limites de migration des données et de rollback soient comprises.