Verdaccio sur VPS : registre npm/yarn/pnpm privé self-hosted

Trois situations rendent un registre npm privé indispensable. La première est la gestion de bibliothèques JavaScript internes : si vous développez un design system, des utilitaires métier ou des clients d'API propres à votre organisation, publier ces packages sur npmjs.org les expose à tout internet. Un registre privé les garde derrière votre infrastructure, versionnés et accessibles uniquement à vos développeurs et à vos pipelines.

La deuxième est la résilience des pipelines CI. npmjs.org tombe en panne plusieurs fois par an, et chaque panne peut bloquer vos déploiements pendant des heures. Verdaccio met en cache chaque package public téléchargé : le deuxième npm install — en CI comme en local — ne sort plus jamais du réseau. Vos builds s'accélèrent et deviennent indépendants de la disponibilité du registre public.

La troisième est le travail hors ligne ou en réseau fermé (air gap). Une fois le cache préchauffé, Verdaccio sert tous les packages vus précédemment sans connexion internet — utile pour les environnements de conformité stricts, les pipelines sur site ou les démos sans Wi-Fi.

Verdaccio répond aux trois en un seul conteneur Docker léger (moins de 128 Mo de RAM), sans base de données externe et sans configuration complexe. Il implémente le protocole npm complet, donc npm, Yarn et pnpm s'y connectent avec un seul paramètre de configuration, sans modifier aucune dépendance.

Verdaccio est l'un des services les plus légers que vous puissiez déployer sur un VPS. La liste des prérequis est intentionnellement courte : un VPS avec 1 vCPU, 512 Mo de RAM (Verdaccio consomme moins de 128 Mo en fonctionnement normal) et Docker installé. Aucun domaine n'est obligatoire pour commencer — vous accédez au registre via un tunnel SSH depuis votre poste ou depuis un runner CI.

Si vous souhaitez un accès permanent pour toute votre équipe ou pour vos pipelines CI hébergés ailleurs, rattachez un domaine depuis votre espace client ServOrbit : nginx le proxifiera automatiquement en HTTPS. Verdaccio fonctionne tout aussi bien derrière ce reverse proxy, et le certificat TLS est géré par ServOrbit sans action de votre part.

Pour le stockage des packages, prévoyez l'espace disque proportionnel à votre usage : les packages publics mis en cache depuis npmjs.org et vos packages privés s'accumulent dans un volume Docker persistant. Pour un usage équipe de 5 à 10 développeurs, quelques gigaoctets suffisent pour la plupart des projets JavaScript.

Par défaut, Verdaccio applique une règle unique : tout package est d'abord recherché localement, puis proxifié vers npmjs.org si absent. Cette règle convient pour démarrer, mais la plupart des équipes veulent affiner le comportement par scope.

La configuration vit dans config.yaml, accessible depuis le volume Docker (verdaccio-storage). La section packages: définit les règles par motif de nom. Pour un scope privé (@acme/*), vous pouvez désactiver le proxy vers npmjs.org (proxy: '') et autoriser uniquement les utilisateurs authentifiés à lire et publier. Pour tous les autres packages (**), vous laissez le proxy vers npmjs actif.

Exemple minimal de configuration de scopes :

packages:
  '@acme/*':
    access: $authenticated
    publish: $authenticated
  '**':
    access: $all
    proxy: npmjs

Après modification, relancez le conteneur : docker compose restart verdaccio. La configuration est prise en compte sans rechargement de la base de packages. Cette approche garantit que vos packages privés ne partent jamais vers npmjs.org, même en cas d'erreur de configuration.

Utiliser Verdaccio dans vos pipelines CI/CD présente deux avantages majeurs : la stabilité des builds (indépendance vis-à-vis de npmjs.org) et l'accès aux packages privés depuis les runners.

Pour GitHub Actions, définissez la variable d'environnement dans votre workflow :

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      NPM_CONFIG_REGISTRY: https://verdaccio.votre-domaine.com
      NPM_CONFIG_//verdaccio.votre-domaine.com/:_authToken: ${{ secrets.VERDACCIO_TOKEN }}

Pour GitLab CI, la syntaxe est équivalente dans la section variables: de votre .gitlab-ci.yml. Le token d'accès s'obtient avec npm token create --registry https://verdaccio.votre-domaine.com depuis n'importe quel compte utilisateur Verdaccio.

Pour le cache de packages publics uniquement (sans packages privés), vous pouvez configurer Verdaccio comme miroir de npmjs.org dans une image Docker de runner dédiée. Les packages sont téléchargés une seule fois par le premier build, puis servis depuis le cache pour tous les builds suivants — les installations node_modules passent de 30–60 secondes à 2–5 secondes.

Par défaut, Verdaccio utilise son propre système d'authentification basé sur un fichier htpasswd. Les comptes créés avec npm adduser y sont stockés avec un hachage bcrypt. Ce mécanisme est suffisant pour une petite équipe, mais Verdaccio supporte aussi des plugins d'authentification tiers : LDAP, GitLab, GitHub OAuth, Keycloak et d'autres.

Pour les tokens d'accès CI, utilisez npm token create --registry https://verdaccio.votre-domaine.com plutôt que de stocker un mot de passe en clair. Les tokens peuvent être révoqués individuellement sans affecter les autres utilisateurs.

Sur ServOrbit, Verdaccio est lié à 127.0.0.1 et exposé uniquement via le reverse proxy nginx. Le port 4873 n'est jamais accessible directement depuis internet — nginx ajoute TLS, et seul le domaine proxifié répond sur 443. Pour une sécurité maximale, activez l'authentification obligatoire pour les lectures (access: $authenticated dans config.yaml) si votre registre contient des packages sensibles. Par défaut, Verdaccio autorise la lecture anonyme — convenable pour un cache de packages publics, mais à restreindre pour les packages propriétaires.