Registre npm privé Verdaccio sur Hetzner : tutoriel 2026

📍 Article principal : Bun monorepo guide complet 2026

Introduction

Une agence ivoirienne capitalise depuis dix-huit mois une bibliothèque de composants Vue et Svelte, des helpers de validation UEMOA, et un client SDK pour quatre fournisseurs de mobile money. Tout ce code représente une dizaine de milliers d’heures-développeur cumulées. Le mettre sur npm public n’est pas envisageable : ces packages contiennent des logiques métier propriétaires, des optimisations spécifiques, et la signature commerciale de l’agence. La solution adoptée : un registre Verdaccio auto-hébergé sur un VPS Hetzner CX22, accessible uniquement par les développeurs autorisés et les CI internes. Coût total : 5 €/mois. Ce tutoriel décrit l’installation pas-à-pas, la configuration de l’authentification, la sécurisation, l’intégration avec Bun, et les bonnes pratiques de sauvegarde. À la fin, vous avez un registre privé fonctionnel qui supporte vos packages internes sans frais récurrents prohibitifs comparé aux solutions cloud (npm Enterprise, GitHub Packages payant).

Prérequis

• VPS Hetzner Cloud (CX22 ou plus) avec Debian 13 ou Ubuntu 24.04
• Domaine pointant vers le VPS (par exemple npm.example.sn)
• Bases SSH, systemd, et reverse proxy (Caddy ou nginx)
• Niveau : intermédiaire — Temps : 1 h 30

Étape 1 — Installer Node et Verdaccio

Verdaccio nécessite Node.js 18 ou supérieur. On installe Node 22 LTS via NVM ou via les paquets officiels Debian/Ubuntu, puis on déploie Verdaccio globalement. L’installation globale n’est pas idéale en théorie mais simplifie considérablement le management opérationnel pour ce service précis.

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
sudo npm install -g verdaccio

Une fois installé, Verdaccio peut être lancé directement avec verdaccio et écoute par défaut sur le port 4873. Pour une installation pérenne, on utilise systemd. On crée un utilisateur dédié verdaccio sans privilège root, on lui assigne un répertoire de stockage des packages, et on configure une unité systemd qui démarre le service au boot.

sudo useradd --system --create-home --home-dir /var/lib/verdaccio verdaccio
sudo mkdir -p /var/lib/verdaccio/storage
sudo chown -R verdaccio:verdaccio /var/lib/verdaccio

Étape 2 — Configurer Verdaccio

Le fichier de configuration /var/lib/verdaccio/config.yaml pilote tout le comportement du registre. Trois sections essentielles : le stockage (où Verdaccio stocke les packages), l’authentification (qui peut publier et consulter), et les uplinks (proxying vers npm public pour les dépendances externes).

# /var/lib/verdaccio/config.yaml
storage: /var/lib/verdaccio/storage
auth:
  htpasswd:
    file: /var/lib/verdaccio/htpasswd
    max_users: 50
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    cache: true
packages:
  '@itskills/*':
    access: $authenticated
    publish: $authenticated
    unpublish: $authenticated
  '@*/*':
    access: $authenticated
    publish: $authenticated
    proxy: npmjs
  '**':
    access: $authenticated
    publish: $authenticated
    proxy: npmjs
listen: 127.0.0.1:4873
log: { type: stdout, format: pretty, level: http }

Cette configuration impose l’authentification pour toute action — accès en lecture, publication, suppression. Les packages scopés @itskills/* sont stockés localement uniquement, jamais proxyés. Les autres packages sont proxyés depuis npm public et mis en cache local pour accélération. L’option listen: 127.0.0.1:4873 restreint Verdaccio à l’écoute locale, le reverse proxy Caddy gérera HTTPS et l’exposition publique.

Étape 3 — Service systemd

# /etc/systemd/system/verdaccio.service
[Unit]
Description=Verdaccio NPM Registry
After=network.target

[Service]
Type=simple
User=verdaccio
Group=verdaccio
ExecStart=/usr/bin/verdaccio --config /var/lib/verdaccio/config.yaml
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now verdaccio
sudo systemctl status verdaccio

Le service démarre automatiquement au boot et redémarre en cas de plantage. Pour suivre les logs en direct : journalctl -u verdaccio -f. Cette commande révèle immédiatement les problèmes de configuration ou les tentatives d’authentification échouées.

Étape 4 — Reverse proxy Caddy avec HTTPS

Caddy gère HTTPS automatiquement et configure le reverse proxy en quelques lignes. On configure le fichier /etc/caddy/Caddyfile pour exposer Verdaccio sur le domaine choisi, ajoute des headers de sécurité, et un rate limit basique pour limiter les abus.

npm.example.sn {
    reverse_proxy localhost:4873
    encode zstd gzip
    header {
        Strict-Transport-Security "max-age=31536000"
        X-Content-Type-Options "nosniff"
    }
    log {
        output file /var/log/caddy/verdaccio.log
        format json
    }
}

Recharger Caddy avec sudo systemctl reload caddy, et le registre est accessible en HTTPS sur https://npm.example.sn. Le certificat Let’s Encrypt est obtenu automatiquement et renouvelé sans intervention. La configuration Caddy reste lisible en cinq lignes, contrastant avec un nginx équivalent qui demanderait quarante lignes de configuration manuelle.

Étape 5 — Créer les comptes utilisateurs

Avant la première utilisation, on crée les comptes des développeurs et des CI. Verdaccio fournit une commande npm dédiée qui pousse l’authentification vers le registre. Chaque développeur exécute cette commande depuis son poste avec ses propres credentials. Les CI utilisent des comptes dédiés avec des mots de passe générés et stockés dans GitHub Secrets.

npm adduser --registry https://npm.example.sn
# Saisir username, password, email

Pour les CI, on crée un utilisateur dédié ci-prod avec un mot de passe robuste, et on stocke le token résultant dans GitHub Secrets sous le nom VERDACCIO_TOKEN. Le workflow CI utilise ce token pour publier les packages internes sans nécessiter de credentials humains.

Étape 6 — Configurer Bun pour le registre privé

Bun lit la configuration npm classique depuis ~/.npmrc et accepte les overrides via bunfig.toml. Pour pointer les packages scopés vers le registre privé tout en laissant les autres aller sur npm public, on configure le scope spécifiquement.

# ~/.npmrc ou .npmrc à la racine du projet
@itskills:registry=https://npm.example.sn
//npm.example.sn/:_authToken=${VERDACCIO_TOKEN}

Avec cette configuration, bun add @itskills/shared télécharge depuis Verdaccio, tandis que bun add hono reste sur npm public. Le mélange est transparent pour les développeurs. Pour publier vers le registre privé, on ajoute "publishConfig": { "registry": "https://npm.example.sn" } dans le package.json du package — la commande bun publish ou changeset publish respecte ce paramètre.

Étape 7 — Stratégie de sauvegarde

Le stockage des packages dans /var/lib/verdaccio/storage est l’actif critique du registre. Une perte signifie reconstruire des mois de capitalisation technique. Trois mesures complémentaires. Premièrement, snapshots Hetzner quotidiens du VPS (gratuit dans le plan, conserve 7 jours par défaut). Deuxièmement, sauvegarde rsync chiffrée nocturne vers une Storage Box Hetzner (3 €/mois pour 1 To, suffisant pour un registre interne). Troisièmement, copie hebdomadaire vers un second fournisseur (Backblaze B2, OVH Object Storage) pour résilience géographique.

# /etc/cron.daily/verdaccio-backup
#!/bin/bash
DATE=$(date +%Y%m%d)
tar czf /tmp/verdaccio-${DATE}.tar.gz -C /var/lib/verdaccio storage htpasswd config.yaml
rclone copy /tmp/verdaccio-${DATE}.tar.gz hetzner-storagebox:verdaccio-backups/
rm /tmp/verdaccio-${DATE}.tar.gz
find /var/lib/verdaccio-snapshots -mtime +7 -delete

Tester la restauration trimestriellement : provisionner un VPS de test, restaurer la sauvegarde, vérifier qu’un npm install @itskills/shared fonctionne contre cette restauration. Sans test régulier, la sauvegarde n’est qu’une illusion de sécurité.

Étape 8 — Sécurité avancée

Trois mesures de défense en profondeur. Fail2ban qui surveille les tentatives d’authentification échouées et bannit les IP fautives — protection contre les brute force. Restriction d’accès par IP via le firewall Hetzner ou Caddy : si tous les développeurs et CI viennent d’IPs connues (bureaux, cloud providers), n’ouvrir l’accès qu’à ces ranges. Audit régulier des packages publiés via npm audit contre le registre privé pour détecter les vulnérabilités introduites dans le code interne.

Pour les packages très sensibles, on peut envisager une signature additionnelle via Sigstore ou un système maison de signature SHA-256 vérifiée à l’install. C’est de l’over-engineering pour 95 % des cas mais devient pertinent dès qu’on traite du code lié aux paiements ou à l’authentification.

Adaptation au contexte ouest-africain

Trois aspects pratiques. Premièrement, héberger Verdaccio à Frankfurt (FRA1) ou Helsinki (HEL1) plutôt qu’aux États-Unis donne une latence acceptable depuis Dakar (90-120 ms) et des coûts en euros prévisibles. Deuxièmement, pour les agences avec plusieurs pays UEMOA, un seul Verdaccio centralisé sert toutes les équipes — pas besoin de réplication multi-région tant que le volume reste sous quelques milliers de téléchargements par jour. Troisièmement, l’investissement en temps (une journée d’installation et configuration) se rentabilise dès qu’on a 3 packages internes et 5 développeurs : la cohérence des versions et le partage transparent du code valent largement le coût opérationnel.

Comparé à GitHub Packages payant (4 $/utilisateur/mois pour le plan Team, 21 $/utilisateur/mois pour Enterprise) ou npm Enterprise (7 $/utilisateur/mois), Verdaccio auto-hébergé représente une économie immédiate substantielle. Pour une agence de 10 développeurs, la différence atteint 50 $/mois soit 600 $/an — somme non négligeable qui peut être réinvestie dans la formation ou les outils.

Erreurs fréquentes

Tutoriels frères

• Configurer un workspace Bun
• Publier sur npm avec Changesets
• CI GitHub Actions pour monorepo Bun

Pour aller plus loin

• 🔝 Pilier : Bun monorepo guide complet
• Hetzner Cloud Afrique 2026 · Caddy et reverse proxy
• Doc : Verdaccio installation

FAQ

Verdaccio peut-il proxy un autre registre privé (GitHub Packages, JFrog) ?
Oui via la section uplinks avec authentification. C’est utile pour fédérer plusieurs registres derrière un point d’accès unique.

Quelle taille de VPS pour 50 développeurs ?
Un CX32 (8 Go RAM, 80 Go SSD) tient confortablement 50 développeurs avec 200 packages internes. Le goulot est généralement le disque, pas le CPU.

Comment migrer depuis npm Enterprise vers Verdaccio ?
Exporter les packages via npm pack, les republier sur Verdaccio. Pour les versions historiques, exporter la base de données du registre source si l’éditeur le permet, sinon accepter de ne garder que les versions récentes.

Verdaccio supporte-t-il les packages binaires (ex: sharp pré-compilé) ?
Oui, comme n’importe quel package npm. Le proxying depuis npm public conserve les binaires natifs.

Alternatives à Verdaccio en 2026

Trois alternatives méritent évaluation selon le contexte. Sonatype Nexus Repository reste la référence en entreprise mais demande plus de ressources serveur (4 Go RAM minimum) et une licence pour les fonctionnalités avancées. JFrog Artifactory offre une plateforme universelle (npm, Maven, Docker, NuGet) avec une UI plus riche, pertinent dès qu’on gère plusieurs écosystèmes en parallèle. GitHub Packages est une option cloud sans installation mais payante au-delà du plan Free, et peut créer une dépendance forte à GitHub. Pour 95 % des cas d’usage des agences ouest-africaines, Verdaccio reste le meilleur ratio fonctionnalité-coût.

Pour les très petites structures (1-3 développeurs) qui ne veulent absolument rien administrer, GitHub Packages dans un dépôt privé peut suffire — coût quelques euros par mois et zéro maintenance. La frontière de pertinence entre GitHub Packages et Verdaccio se situe autour de 5 développeurs ou de la première fois où l’on commence à rencontrer des limites de quotas du plan gratuit.

Monitoring et observabilité

Pour superviser le registre en production, deux niveaux. Au niveau infrastructure, Netdata ou Glances installé sur le VPS expose CPU, RAM, IO disque, traffic réseau via un dashboard web léger protégé par mot de passe. Cette supervision détecte rapidement un disque qui se remplit (cache uplink qui grossit) ou une charge anormale (tentative de déni de service). Au niveau applicatif, les logs JSON de Verdaccio contiennent chaque requête avec son code de statut, son chemin, et son utilisateur. Une analyse périodique (logwatch, Loki, ou simplement jq sur les logs Caddy) révèle les patterns d’usage et les anomalies.

Pour les alertes, configurer Uptime Kuma sur un autre VPS qui interroge l’endpoint /-/ping de Verdaccio toutes les 60 secondes. En cas d’indisponibilité, notification immédiate via Telegram ou Discord. Cette double couche — supervision locale + sonde externe — couvre l’essentiel des incidents possibles. Pour aller plus loin, intégrer Sentry pour les erreurs applicatives et Loki pour la centralisation des logs reste optionnel jusqu’à plusieurs centaines d’utilisateurs concurrents.

Cas avancé : registre multi-région et réplication

Pour les agences qui démarrent à scaler internationalement (par exemple un studio dakarois qui ouvre une antenne à Paris ou à Casablanca), la latence du registre peut devenir un sujet. Plusieurs approches coexistent. La plus simple : un Cloudflare devant Verdaccio avec cache agressif des tarballs (les fichiers réellement consommés). Le edge sert directement les fichiers depuis Lagos, Paris, ou tout autre PoP, sans solliciter le serveur central — gain de latence majeur pour la même infrastructure. La plus robuste : deux instances Verdaccio dans deux régions Hetzner différentes (FRA1 et HEL1) avec une synchronisation des storages via rsync nocturne. Plus complexe à maintenir mais offre une vraie résilience géographique en cas de panne d’un datacenter entier.

Pour la majorité des structures ouest-africaines qui démarrent ou consolident, ce niveau de complexité est prématuré. Un seul Verdaccio bien sauvegardé tient parfaitement les besoins de 50 développeurs avec quelques milliers de téléchargements par jour. La règle pratique : ne complexifier que face à un problème concret avéré, jamais en anticipation théorique. Mesurer d’abord la latence ressentie par les développeurs depuis leurs vrais postes de travail, puis décider si l’investissement multi-région se justifie.