Verdaccio zelf hosten in 2026: npm-authenticatie, storage en TLS

Verdaccio zelf hosten wordt interessant bij de eerste redeploy, niet bij de eerste docker run. Als npm-clients authenticatie naar een andere host sturen of package storage alleen-lezen is, kan Docker nog steeds een volledig gezond proces rapporteren. De onderstaande deployment is opgebouwd rond observeerbaar gedrag: inloggen met npm, een scoped package publiceren, het vanuit een clean project installeren en bevestigen dat een upstream package in de cache staat.

De beoogde rol van Verdaccio is duidelijk: een private npm registry voor interne packages. Die omschrijving vertelt ons wat publiek moet blijven, wat privé moet blijven en wat een back-up moet kunnen herstellen.

Poorten, processen en private services

Een bruikbaar Verdaccio-diagram toont de publieke route, private poort 4873, de state boundary en alle ondersteunende vereisten. Markeer welke pijlen credentials bevatten en welke gewoon gebruikersverkeer vervoeren. Het netwerkcontract voor Verdaccio bestaat uit persistente configuratie, htpasswd-opslag en optionele object storage. Houd private endpoints op interne DNS, sta alleen noodzakelijke uitgaande verbindingen toe en geef Verdaccio een gescopeerde servicecredential.

Bewijs het diagram met één echte actie: inloggen met npm, een scoped package publiceren, het vanuit een clean project installeren en bevestigen dat een upstream package in de cache staat. De verwachte druk komt van tarball-opslag, metadata-operaties, gelijktijdige installaties en latency naar geconfigureerde upstream registries; monitor dat pad in plaats van alle HTTP-requests als gelijkwaardig te behandelen.

Maak van het lokale commando een inspecteerbare service

Gebruik een commando dat elke belangrijke keuze zichtbaar maakt. Deze basisconfiguratie bindt Verdaccio aan de loopback van de host, voegt de bekende datamounts toe en levert de eerste vereiste instelling. Voeg de beoordeelde verbindingsinstellingen toe voor persistente configuratie, htpasswd-opslag en optionele object storage; gebruik private namen voor private services.

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

Vervang floating tags door een geteste versie of digest. Inspecteer na het opstarten docker logs --tail 200 verdaccio en bevestig dat het proces op 4873 luistert. Voer daarna de Verdaccio-acceptatieactie uit; een response van de rootpagina bewijst niet dat het volledige scenario slaagt: log in met npm, publiceer een scoped package, installeer het vanuit een clean project en bevestig dat een upstream package in de cache staat.

TLS is eenvoudig; gegenereerde URL's niet

Stel de publieke URL en de npm registry-URL in op dezelfde HTTPS-origin. Stuur de gekozen hostname door naar containerpoort 4873, geef de oorspronkelijke host en het HTTPS-schema door en publiceer geen tweede directe origin.

Test Verdaccio vanuit een clean externe client. Maak onderscheid tussen een ingress-fout en de bekende applicatiegrens — npm-clients sturen authenticatie naar een andere host of package storage is alleen-lezen. Een certificaat-, DNS- of 502-fout hoort bij routing; een request die Verdaccio bereikt en pas daarna faalt, hoort bij applicatiestate, capaciteit of een ondersteunende vereiste. De handleiding voor TLS met een custom domain behandelt de eerste groep.

Verdaccio herstellen op een lege host

Bij Verdaccio begint veilige redeployment met package tarballs, metadata, configuratie en authenticatiebestanden. Mount /verdaccio/storage voordat je bootstrap uitvoert, schrijf onschadelijke voorbeelddata en vervang de container om te bewijzen dat dit pad daadwerkelijk persistent is. Test het pad door de container te vervangen terwijl de onschadelijke voorbeelddata nog aanwezig is; zo vind je mounts die één directory te hoog of te laag wijzen.

Test vervolgens disaster recovery op een lege host. Gebruik waar nodig een applicatieconsistente database-export en controleer of private tarballs, metadata, users en configuratie terugkomen en het clean project hetzelfde package-integrity-resultaat oplevert. De handleiding voor databaseback-ups die je daadwerkelijk hebt teruggezet biedt een sterker doel dan alleen controleren of er een archiefbestand is aangemaakt.

Credentials, rollen en blootgestelde oppervlakken

Bij Verdaccio is het waardevolle oppervlak niet per se de landingspagina. De grootste fout is anoniem publiceren toestaan of een writable uplink-configuratie gebruiken. Bestrijd dit bewust: weiger anoniem publiceren, beperk maintainers met scopes en zorg dat npm-authenticatie gekoppeld blijft aan exact de HTTPS registry-host.

VERDACCIO_PUBLIC_URL is configuratie en geen secret; houd de waarde expliciet en bescherm de afzonderlijke credentials die Verdaccio gebruikt. Gebruik een unprivileged container user wanneer de image dit ondersteunt en mount geen niet-gerelateerde credentials. Pas rate- of sizelimits toe bij ingress, waar onbetrouwbare workloads tarball-opslag, metadata-operaties, gelijktijdige installaties en latency naar geconfigureerde upstream registries kunnen belasten.

Failure drills voor Verdaccio

Capaciteitstests moeten tarball-opslag, metadata-operaties, gelijktijdige installaties en latency naar geconfigureerde upstream registries belasten, niet herhaaldelijk een request naar / sturen. Voer het scenario “inloggen met npm, een scoped package publiceren, het vanuit een clean project installeren en bevestigen dat een upstream package in de cache staat” uit met realistische concurrency en leg latency, error rate en groei van de storage vast.

Bij upgradeplanning moet je rekening houden met dit risico: configsyntaxis, authenticatieplugins en package metadata moeten worden getest tegen de beoogde major version van Verdaccio. Test de nieuwe release met representatieve input, voer daarna de acceptatietransactie opnieuw uit en vergelijk het resultaat. Als npm-clients authenticatie naar een andere host sturen of package storage alleen-lezen is, leg dan de mislukte transactie vast en inspecteer de eerste betrokken grens in plaats van ervan uit te gaan dat ingress verantwoordelijk is.

Bewijs de Verdaccio-deployment end-to-end

Gebruik verkeer van de eerste gebruiker niet als acceptatietest voor Verdaccio. Bereid onschadelijke voorbeeldstate voor en voer de volledige actie uit: “inloggen met npm, een scoped package publiceren, het vanuit een clean project installeren en bevestigen dat een upstream package in de cache staat”. Noteer de exacte publieke URL, het resultaat, de image reference en het loginterval dat bij de run hoort.

Vervang de container en herhaal dit zonder de data opnieuw op te bouwen. Herstel vervolgens op een lege host; de herstelvoorwaarde is dat private tarballs, metadata, users en configuratie terugkomen en het clean project dezelfde package-integrity oplevert. Observeer bij elke run tarball-opslag, metadata-operaties, gelijktijdige installaties en latency naar geconfigureerde upstream registries en definieer een alert rond verslechtering van de transactie, niet rond inactieve container-metrics.

Eén laatste controle moet expres mislukken: ontzeg de testidentiteit tijdelijk toegang tot persistente configuratie, htpasswd-opslag en optionele object storage. Controleer of de resulterende Verdaccio-melding de relevante grens identificeert, in plaats van dataverwijdering of een eindeloze restart te veroorzaken. Herstel de geldige situatie en bevestig dat dezelfde voorbeeldtransactie slaagt. Houd deze korte drill in de releasechecklist.

Houd Verdaccio expliciet terwijl Dockup routing afhandelt

Voor Verdaccio kan Dockup de route en het TLS-certificaat aanmaken, mounts behouden, secrets leveren en persistente configuratie, htpasswd-opslag en optionele object storage via private networking beschikbaar maken, terwijl de deployment op Dockup of gekoppelde servers plaatsvindt.

De release gate blijft de concrete Verdaccio-transactie: inloggen met npm, een scoped package publiceren, het vanuit een clean project installeren en bevestigen dat een upstream package in de cache staat. Controleer ook de herstelvoorwaarde — private tarballs, metadata, users en configuratie komen terug en het clean project installeert dezelfde package-integrity. Deze twee controles laten zien of de deployment werkt en of deze kan worden hersteld.

Veelgestelde vragen

Wat heeft Verdaccio nodig voor een productiedeployment?

Routeer de Verdaccio-container via poort 4873 door één HTTPS-origin. De ondersteunende netwerkvereiste bestaat uit persistente configuratie, htpasswd-opslag en optionele object storage. Verklaar Verdaccio pas gereed wanneer je kunt inloggen met npm, een scoped package kunt publiceren, het vanuit een clean project kunt installeren en kunt bevestigen dat een upstream package in de cache staat.

Welke Verdaccio-data hoort in een back-up?

Maak /verdaccio/storage persistent en neem package tarballs, metadata, configuratie en authenticatiebestanden op in hetzelfde herstelmanifest. Een clean Verdaccio-herstel slaagt alleen wanneer private tarballs, metadata, users en configuratie terugkomen en het clean project dezelfde package-integrity installeert.

Heeft Verdaccio HTTPS nodig achter een reverse proxy?

Gebruik HTTPS voor de publieke Verdaccio-origin en houd poort 4873 op de interne route. Pas de Verdaccio-instelling correct toe: stel de publieke URL en de npm registry-URL in op dezelfde HTTPS-origin. Voor Verdaccio beschermt HTTPS credentials of gebruikerscontent tijdens transport en blijft clientgedrag dat afhankelijk is van de origin consistent.

Hoe test je een Verdaccio-upgrade?

Herstel de huidige Verdaccio-state in een geïsoleerde deployment, pas de kandidaatversie toe en herhaal de acceptatietransactie. Let extra goed op, omdat configsyntaxis, authenticatieplugins en package metadata moeten worden getest tegen de beoogde major version van Verdaccio. Houd de vorige Verdaccio-image beschikbaar totdat de grenzen voor datamigratie en rollback duidelijk zijn.