Comment auto-héberger Verdaccio en 2026 : authentification npm, stockage et TLS

L’auto-hébergement de Verdaccio devient intéressant dès le premier redéploiement, et non dès le premier docker run. Si les clients npm envoient leurs identifiants à un autre hôte ou si le stockage des paquets est en lecture seule, Docker peut tout de même signaler un processus parfaitement sain. Le déploiement ci-dessous s’organise autour de comportements observables : se connecter avec npm, publier un paquet scoped, l’installer depuis un projet vierge et confirmer qu’un paquet upstream est mis en cache.

Le rôle prévu de Verdaccio est explicite : registry npm privée pour les paquets internes. Cette description indique ce qui doit rester public, ce qui doit rester privé et ce qu’une sauvegarde doit pouvoir reconstruire.

Ports, processus et services privés

Un schéma utile de Verdaccio présente la route publique, le port privé 4873, la limite d’état et toutes les exigences connexes. Indiquez quelles flèches transportent des identifiants et lesquelles correspondent à un trafic utilisateur ordinaire. Le contrat réseau de Verdaccio repose sur une configuration persistante, un stockage htpasswd et, éventuellement, un object storage. Conservez les endpoints privés sur un DNS interne, n’autorisez que les appels sortants nécessaires et attribuez à Verdaccio un credential de service limité à un périmètre précis.

Validez le schéma avec une action réelle : connectez-vous avec npm, publiez un paquet scoped, installez-le depuis un projet vierge et confirmez qu’un paquet upstream est mis en cache. Les points de pression probables sont le stockage des tarballs, les opérations sur les métadonnées, les installations concurrentes et la latence vers les registries upstream configurées ; surveillez ce chemin au lieu de traiter toutes les requêtes HTTP de la même manière.

Transformer la commande locale en service inspectable

Utilisez une commande qui expose chaque choix important. Cette configuration de base lie Verdaccio à la loopback de l’hôte, ajoute les mounts de données connus et fournit le premier paramètre requis. Ajoutez les paramètres de connexion validés pour la configuration persistante, le stockage htpasswd et l’object storage facultatif ; utilisez des noms privés pour les services privés.

docker run -d \
  --name verdaccio \
  --restart unless-stopped \
  -p 127.0.0.1:4873:4873 \
  -v verdaccio-data:/verdaccio/storage \
  -e VERDACCIO_PUBLIC_URL=https://app.example.com \
  verdaccio/verdaccio:latest

Remplacez les tags flottants par une version ou un digest testé. Après le démarrage, inspectez docker logs --tail 200 verdaccio et confirmez que le processus écoute sur le port 4873. Exécutez ensuite l’action d’acceptation de Verdaccio ; une réponse de la page racine ne peut pas prouver que le scénario complet fonctionne : connectez-vous avec npm, publiez un paquet scoped, installez-le depuis un projet vierge et confirmez qu’un paquet upstream est mis en cache.

TLS est simple ; les URL générées ne le sont pas

Définissez l’URL publique et l’URL de registry npm sur la même origine HTTPS. Acheminez le nom d’hôte choisi vers le port 4873 du conteneur, transmettez l’hôte d’origine et le schéma HTTPS, et évitez de publier une seconde origine directe.

Testez Verdaccio depuis un client externe vierge. Distinguez une défaillance de l’ingress de la limite applicative connue — les clients npm envoient leurs identifiants à un autre hôte ou le stockage des paquets est en lecture seule. Une erreur de certificat, de DNS ou de type 502 relève du routage ; une requête qui atteint Verdaccio mais échoue ensuite relève de l’état applicatif, de la capacité ou d’une exigence connexe. Le guide TLS avec domaine personnalisé couvre le premier groupe.

Restaurer Verdaccio sur un hôte vierge

Pour Verdaccio, la sécurité du redéploiement commence par les tarballs des paquets, les métadonnées, la configuration et les fichiers d’authentification. Montez /verdaccio/storage avant le bootstrap, écrivez des données d’exemple inoffensives et remplacez le conteneur pour prouver que ce chemin est réellement persistant. Testez ce chemin en remplaçant le conteneur tant que les données d’exemple inoffensives sont présentes ; cela révèle les mounts pointant un niveau de répertoire trop haut ou trop bas.

Testez ensuite la reprise après sinistre sur un hôte vierge. Utilisez si nécessaire un export de base de données cohérent du point de vue applicatif et vérifiez que les tarballs privés, les métadonnées, les utilisateurs et la configuration sont restaurés et que le projet vierge installe un paquet présentant la même intégrité. Le guide des sauvegardes de bases de données restaurées fournit une cible plus exigeante que la simple vérification de la création d’un fichier d’archive.

Identifiants, rôles et surfaces exposées

Pour Verdaccio, la surface importante n’est pas forcément la landing page. L’erreur principale consiste à autoriser la publication anonyme ou à utiliser une configuration d’uplink accessible en écriture. Corrigez cela délibérément : interdisez la publication anonyme, limitez les droits des maintainers et associez l’authentification npm à l’hôte exact de la registry HTTPS.

VERDACCIO_PUBLIC_URL est une configuration, pas un secret ; gardez sa valeur explicite tout en protégeant les credentials distincts utilisés par Verdaccio. Utilisez un utilisateur de conteneur non privilégié lorsque l’image le permet et ne montez aucun credential sans rapport. Appliquez les limites de débit ou de taille au niveau de l’ingress lorsque des opérations non fiables peuvent consommer le stockage des tarballs, les opérations sur les métadonnées, les installations concurrentes et la latence vers les registries upstream configurées.

Scénarios de panne pour Verdaccio

Les tests de capacité doivent solliciter le stockage des tarballs, les opérations sur les métadonnées, les installations concurrentes et la latence vers les registries upstream configurées, et non répéter une requête vers /. Exécutez le scénario « se connecter avec npm, publier un paquet scoped, l’installer depuis un projet vierge et confirmer qu’un paquet upstream est mis en cache » avec une concurrence réaliste, puis relevez la latence, le taux d’erreur et la croissance du stockage.

La planification des mises à niveau doit tenir compte de ce risque : la syntaxe de configuration, les plugins d’authentification et les métadonnées des paquets doivent être testés avec la version majeure cible de Verdaccio. Testez la nouvelle version avec des données représentatives, puis répétez la transaction d’acceptation et comparez son résultat. Si les clients npm envoient leurs identifiants à un autre hôte ou si le stockage des paquets est en lecture seule, capturez la transaction en échec et inspectez la première limite impliquée au lieu de supposer que l’ingress est responsable.

Valider le déploiement de Verdaccio de bout en bout

Ne faites pas du trafic du premier utilisateur le test d’acceptation de Verdaccio. Préparez un état d’exemple inoffensif et exécutez l’action complète « se connecter avec npm, publier un paquet scoped, l’installer depuis un projet vierge et confirmer qu’un paquet upstream est mis en cache ». Notez l’URL publique exacte, le résultat, la référence de l’image et l’intervalle de logs associés à l’exécution.

Remplacez le conteneur et répétez l’opération sans reconstruire les données. Récupérez ensuite le service sur un hôte vierge ; la condition de reprise est que les tarballs privés, les métadonnées, les utilisateurs et la configuration soient restaurés et que le projet vierge installe un paquet présentant la même intégrité. Observez le stockage des tarballs, les opérations sur les métadonnées, les installations concurrentes et la latence vers les registries upstream configurées à chaque passage, et définissez une alerte autour de la dégradation de la transaction plutôt qu’autour des métriques d’inactivité du conteneur.

Une dernière vérification doit échouer volontairement : refusez temporairement à l’identité de test l’accès à la configuration persistante, au stockage htpasswd et à l’object storage facultatif. Vérifiez que le message produit par Verdaccio identifie la limite concernée au lieu d’entraîner une suppression de données ou un redémarrage sans fin. Restaurez la condition valide et confirmez que la même transaction d’exemple réussit. Conservez ce test court dans la checklist de release.

Garder Verdaccio explicite pendant que Dockup gère le routage

Pour Verdaccio, Dockup peut créer la route et le certificat TLS, préserver les mounts, fournir les secrets et placer la configuration persistante, le stockage htpasswd et l’object storage facultatif sur un réseau privé, tout en déployant sur Dockup ou sur des serveurs associés.

La release gate reste toutefois la transaction concrète de Verdaccio : se connecter avec npm, publier un paquet scoped, l’installer depuis un projet vierge et confirmer qu’un paquet upstream est mis en cache. Vérifiez également la condition de restauration — les tarballs privés, les métadonnées, les utilisateurs et la configuration sont restaurés et le projet vierge installe un paquet présentant la même intégrité. Ces deux vérifications montrent si le déploiement fonctionne et s’il peut être restauré.

Questions fréquemment posées

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

Acheminez le conteneur Verdaccio sur le port 4873 via une seule origine HTTPS. L’exigence réseau connexe est une configuration persistante, un stockage htpasswd et, éventuellement, un object storage. Ne considérez pas Verdaccio comme prêt tant que vous ne pouvez pas vous connecter avec npm, publier un paquet scoped, l’installer depuis un projet vierge et confirmer qu’un paquet upstream est mis en cache.

Quelles données de Verdaccio doivent figurer dans une sauvegarde ?

Rendez /verdaccio/storage persistant et incluez les tarballs des paquets, les métadonnées, la configuration et les fichiers d’authentification dans le même manifeste de reprise. Une restauration propre de Verdaccio n’est validée que lorsque les tarballs privés, les métadonnées, les utilisateurs et la configuration sont restaurés et que le projet vierge installe un paquet présentant la même intégrité.

Verdaccio nécessite-t-il HTTPS derrière un reverse proxy ?

Utilisez HTTPS pour l’origine publique de Verdaccio et conservez le port 4873 sur la route interne. Appliquez correctement le paramètre Verdaccio : définissez l’URL publique et l’URL de registry npm sur la même origine HTTPS. Pour Verdaccio, HTTPS protège les credentials ou le contenu utilisateur en transit et garantit un comportement cohérent des clients sensible à l’origine.

Comment tester une mise à niveau de Verdaccio ?

Restaurez l’état actuel de Verdaccio dans un déploiement isolé, appliquez la version candidate et répétez sa transaction d’acceptation. Soyez particulièrement attentif, car la syntaxe de configuration, les plugins d’authentification et les métadonnées des paquets doivent être testés avec la version majeure cible de Verdaccio. Conservez l’image Verdaccio précédente jusqu’à ce que les limites de migration des données et de rollback soient comprises.