Come fare self-hosting di Verdaccio nel 2026: autenticazione npm, storage e TLS

Il self-hosting di Verdaccio diventa interessante al primo redeploy, non al primo docker run. Se i client npm inviano le credenziali a un host diverso o lo storage dei pacchetti è in sola lettura, Docker può comunque segnalare un processo perfettamente integro. Il deployment seguente è organizzato intorno a comportamenti osservabili: accedere con npm, pubblicare un pacchetto con scope, installarlo da un progetto pulito e verificare che un pacchetto upstream venga messo in cache.

Il ruolo previsto per Verdaccio è esplicito: un registry npm privato per i pacchetti interni. Questa descrizione chiarisce cosa deve restare pubblico, cosa deve rimanere privato e cosa deve ricostruire un backup.

Porte, processi e servizi privati

Un diagramma utile di Verdaccio mostra il percorso pubblico, la porta privata 4873, il confine dello stato e tutti i requisiti di supporto. Indica quali frecce trasportano credenziali e quali rappresentano il normale traffico degli utenti. Il contratto di rete per Verdaccio comprende configurazione persistente, storage htpasswd e object storage opzionale. Mantieni gli endpoint privati su DNS interno, consenti solo le chiamate outbound necessarie e assegna a Verdaccio una credenziale di servizio con scope limitato.

Dimostra il diagramma con un'azione reale: accedi con npm, pubblica un pacchetto con scope, installalo da un progetto pulito e verifica che un pacchetto upstream venga messo in cache. La pressione probabile deriva dallo storage dei tarball, dalle operazioni sui metadati, dalle installazioni concorrenti e dalla latenza verso i registry upstream configurati; monitora questo percorso invece di trattare tutte le richieste HTTP allo stesso modo.

Trasforma il comando locale in un servizio ispezionabile

Usa un comando che renda esplicite tutte le scelte importanti. Questa configurazione di base associa Verdaccio al loopback dell'host, aggiunge i mount dei dati noti e fornisce la prima impostazione necessaria. Aggiungi le impostazioni di connessione verificate per la configurazione persistente, lo storage htpasswd e l'object storage opzionale; usa nomi privati per i servizi privati.

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

Sostituisci i tag mobili con una versione o un digest verificati. Dopo l'avvio, esamina docker logs --tail 200 verdaccio e conferma che il processo sia in ascolto sulla porta 4873. Esegui quindi l'azione di acceptance di Verdaccio; una risposta della root non può dimostrare che l'intero scenario abbia esito positivo: accedi con npm, pubblica un pacchetto con scope, installalo da un progetto pulito e verifica che un pacchetto upstream venga messo in cache.

Il TLS è semplice; gli URL generati no

Imposta l'URL pubblico e l'URL del registry npm sulla stessa origine HTTPS. Inoltra l'hostname scelto alla porta 4873 del container, trasferisci l'host originale e lo schema HTTPS ed evita di pubblicare una seconda origine diretta.

Testa Verdaccio da un client esterno pulito. Separa i problemi di ingress dal confine applicativo noto: i client npm inviano le credenziali a un host diverso oppure lo storage dei pacchetti è in sola lettura. Un errore di certificato, DNS o 502 riguarda il routing; una richiesta che raggiunge Verdaccio e fallisce in seguito riguarda lo stato dell'applicazione, la capacità o un suo requisito di supporto. La guida al TLS automatico per domini personalizzati tratta il primo gruppo.

Ripristina Verdaccio su un host vuoto

Per Verdaccio, la sicurezza del redeploy parte dai tarball dei pacchetti, dai metadati, dalla configurazione e dai file di autenticazione. Monta /verdaccio/storage prima del bootstrap, scrivi dati di esempio innocui e sostituisci il container per dimostrare che quel percorso sia realmente persistente. Verifica il percorso sostituendo il container mentre i dati di esempio innocui sono ancora presenti; in questo modo puoi individuare i mount puntati a una directory troppo alta o troppo bassa.

Poi testa il disaster recovery su un host vuoto. Usa, quando necessario, un export del database coerente con l'applicazione e verifica che tarball privati, metadati, utenti e configurazione vengano ripristinati e che il progetto pulito installi lo stesso pacchetto con la medesima integrità. La guida ai backup dei database sottoposti a ripristino offre un obiettivo più solido del semplice controllo che sia stato creato un file di archivio.

Credenziali, ruoli e superfici esposte

Per Verdaccio, la superficie di valore non coincide necessariamente con la landing page. L'errore principale consiste nel consentire la pubblicazione anonima o nell'usare una configurazione uplink scrivibile. Contrasta deliberatamente questo rischio: nega la pubblicazione anonima, assegna scope ai maintainer e mantieni l'autenticazione npm associata all'host HTTPS esatto del registry.

VERDACCIO_PUBLIC_URL è una configurazione, non un segreto; mantieni esplicito il suo valore proteggendo al contempo le credenziali separate utilizzate da Verdaccio. Usa un utente non privilegiato per il container quando l'immagine lo supporta e non montare credenziali non pertinenti. Applica limiti di velocità o dimensione all'ingress, dove il traffico non attendibile può consumare storage per i tarball, operazioni sui metadati, installazioni concorrenti e latenza verso i registry upstream configurati.

Esercitazioni sui guasti di Verdaccio

I test di capacità devono esercitare lo storage dei tarball, le operazioni sui metadati, le installazioni concorrenti e la latenza verso i registry upstream configurati, non una richiesta ripetuta a /. Esegui lo scenario “accedi con npm, pubblica un pacchetto con scope, installalo da un progetto pulito e verifica che un pacchetto upstream venga messo in cache” con concorrenza realistica e registra latenza, tasso di errore e crescita dello storage.

La pianificazione degli upgrade deve tenere conto di questo rischio: la sintassi della configurazione, i plugin di autenticazione e i metadati dei pacchetti devono essere testati rispetto alla major version di Verdaccio di destinazione. Testa la nuova release con input rappresentativi, quindi ripeti la transazione di acceptance e confrontane il risultato. Se i client npm inviano le credenziali a un host diverso o lo storage dei pacchetti è in sola lettura, acquisisci la transazione che fallisce e ispeziona il primo confine coinvolto invece di presumere che la responsabilità sia dell'ingress.

Dimostra il deployment di Verdaccio end to end

Non usare il traffico del primo utente come test di acceptance per Verdaccio. Prepara uno stato di esempio innocuo ed esegui l'azione completa “accedi con npm, pubblica un pacchetto con scope, installalo da un progetto pulito e verifica che un pacchetto upstream venga messo in cache”. Annota l'URL pubblico esatto, il risultato, il riferimento all'immagine e l'intervallo dei log associati all'esecuzione.

Sostituisci il container e ripeti l'operazione senza ricreare i dati. Poi esegui il ripristino su un host vuoto; la condizione di ripristino richiede che tarball privati, metadati, utenti e configurazione vengano recuperati e che il progetto pulito installi lo stesso pacchetto con la medesima integrità. Osserva lo storage dei tarball, le operazioni sui metadati, le installazioni concorrenti e la latenza verso i registry upstream configurati a ogni passaggio e definisci un alert sul degrado della transazione, non sulle metriche di inattività del container.

Un ultimo controllo dovrebbe fallire intenzionalmente: nega temporaneamente all'identità di test l'accesso alla configurazione persistente, allo storage htpasswd e all'object storage opzionale. Verifica che il messaggio risultante di Verdaccio identifichi il confine pertinente invece di attivare l'eliminazione dei dati o un riavvio infinito. Ripristina la condizione valida e conferma che la stessa transazione di esempio abbia esito positivo. Mantieni questa breve esercitazione nella checklist di release.

Mantieni Verdaccio esplicito mentre Dockup gestisce il routing

Per Verdaccio, Dockup può creare il percorso e il certificato TLS, preservare i mount, distribuire i secret e collocare la configurazione persistente, lo storage htpasswd e l'object storage opzionale su una rete privata, eseguendo il deployment su Dockup o su server collegati.

Il release gate resta comunque la transazione concreta di Verdaccio: accedere con npm, pubblicare un pacchetto con scope, installarlo da un progetto pulito e verificare che un pacchetto upstream venga messo in cache. Verifica inoltre la condizione di ripristino: tarball privati, metadati, utenti e configurazione devono essere recuperati e il progetto pulito deve installare lo stesso pacchetto con la medesima integrità. Questi due controlli mostrano se il deployment funziona e se può essere ripristinato.

Domande frequenti

Cosa serve a Verdaccio per un deployment in produzione?

Instrada il container Verdaccio sulla porta 4873 attraverso un'unica origine HTTPS. Il requisito di rete di supporto comprende configurazione persistente, storage htpasswd e object storage opzionale. Non considerare Verdaccio pronto finché non puoi accedere con npm, pubblicare un pacchetto con scope, installarlo da un progetto pulito e verificare che un pacchetto upstream venga messo in cache.

Quali dati di Verdaccio devono essere inclusi in un backup?

Rendi persistente /verdaccio/storage e includi tarball dei pacchetti, metadati, configurazione e file di autenticazione nello stesso manifest di ripristino. Un ripristino pulito di Verdaccio ha esito positivo solo quando tarball privati, metadati, utenti e configurazione vengono recuperati e il progetto pulito installa lo stesso pacchetto con la medesima integrità.

Verdaccio richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origine pubblica di Verdaccio e mantieni la porta 4873 sul percorso interno. Applica correttamente l'impostazione di Verdaccio: imposta l'URL pubblico e l'URL del registry npm sulla stessa origine HTTPS. Per Verdaccio, HTTPS protegge le credenziali o i contenuti degli utenti durante il transito e mantiene coerente il comportamento del client sensibile all'origine.

Come si deve testare un upgrade di Verdaccio?

Ripristina lo stato corrente di Verdaccio in un deployment isolato, applica la versione candidata e ripeti la relativa transazione di acceptance. Presta particolare attenzione a questo aspetto, perché la sintassi della configurazione, i plugin di autenticazione e i metadati dei pacchetti devono essere testati rispetto alla major version di Verdaccio di destinazione. Conserva la precedente immagine di Verdaccio finché non avrai compreso i confini della migrazione dei dati e del rollback.