Πώς να κάνετε self-host το Verdaccio το 2026: npm Auth, Storage και TLS

Το self-hosting του Verdaccio αποκτά ενδιαφέρον στο πρώτο redeploy, όχι στο πρώτο docker run. Αν οι npm clients στέλνουν authentication σε διαφορετικό host ή το package storage είναι read-only, το Docker μπορεί και πάλι να αναφέρει ότι η διεργασία είναι απολύτως healthy. Η παρακάτω εγκατάσταση είναι οργανωμένη γύρω από παρατηρήσιμη συμπεριφορά: σύνδεση με npm, δημοσίευση ενός scoped package, εγκατάστασή του από ένα clean project και επιβεβαίωση ότι ένα upstream package έχει γίνει cached.

Ο ρόλος του Verdaccio είναι σαφής: private npm registry για internal packages. Αυτή η περιγραφή μάς δείχνει τι πρέπει να παραμείνει public, τι πρέπει να μείνει private και τι χρειάζεται να ανακατασκευάσει ένα backup.

Ports, processes και private services

Ένα χρήσιμο διάγραμμα του Verdaccio δείχνει το public route, το private port 4873, το όριο του state και κάθε supporting requirement. Σημειώστε ποια arrows μεταφέρουν credentials και ποια είναι απλή κίνηση χρηστών. Το network contract για το Verdaccio είναι persistent configuration, htpasswd storage και προαιρετικό object storage. Κρατήστε τα private endpoints σε internal DNS, επιτρέψτε μόνο τα απαραίτητα outbound calls και δώστε στο Verdaccio ένα scoped service credential.

Αποδείξτε το διάγραμμα με μία πραγματική ενέργεια: συνδεθείτε με npm, δημοσιεύστε ένα scoped package, εγκαταστήστε το από ένα clean project και επιβεβαιώστε ότι ένα upstream package έχει γίνει cached. Η πιθανότερη πίεση προέρχεται από το tarball storage, τις metadata operations, τα concurrent installs και το latency προς τα configured upstream registries· παρακολουθήστε αυτή τη διαδρομή αντί να αντιμετωπίζετε όλα τα HTTP requests ως ισοδύναμα.

Μετατρέψτε την τοπική εντολή σε inspectable service

Χρησιμοποιήστε μια εντολή που αποκαλύπτει κάθε σημαντική επιλογή. Αυτό το baseline κάνει bind το Verdaccio στο host loopback, προσθέτει τα γνωστά data mounts και παρέχει την πρώτη απαιτούμενη ρύθμιση. Προσθέστε τα εγκεκριμένα connection settings για persistent configuration, htpasswd storage και προαιρετικό object storage· χρησιμοποιήστε private names για τα 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

Αντικαταστήστε τα floating tags με μια tested version ή digest. Μετά την εκκίνηση, ελέγξτε το docker logs --tail 200 verdaccio και επιβεβαιώστε ότι η διεργασία ακούει στο 4873. Στη συνέχεια εκτελέστε το acceptance action του Verdaccio· μια απόκριση από τη root page δεν αποδεικνύει ότι το πλήρες σενάριο λειτουργεί: συνδεθείτε με npm, δημοσιεύστε ένα scoped package, εγκαταστήστε το από ένα clean project και επιβεβαιώστε ότι ένα upstream package έχει γίνει cached.

Το TLS είναι εύκολο· τα generated URLs όχι

Ορίστε το public URL και το npm registry URL στο ίδιο HTTPS origin. Στείλτε το επιλεγμένο hostname στο container port 4873, προωθήστε το original host και το HTTPS scheme και αποφύγετε τη δημοσίευση ενός δεύτερου direct origin.

Δοκιμάστε το Verdaccio από έναν clean external client. Διαχωρίστε ένα ingress failure από το γνωστό application boundary — οι npm clients στέλνουν authentication σε διαφορετικό host ή το package storage είναι read-only. Ένα certificate, DNS ή 502 error ανήκει στο routing· ένα request που φτάνει στο Verdaccio και αποτυγχάνει αργότερα ανήκει στο application state, το capacity ή κάποιο supporting requirement. Ο οδηγός για TLS με custom domain καλύπτει την πρώτη κατηγορία.

Κάντε restore το Verdaccio σε άδειο host

Για το Verdaccio, η ασφάλεια στο redeploy ξεκινά από τα package tarballs, τα metadata, το config και τα authentication files. Κάντε mount το /verdaccio/storage πριν από το bootstrap, γράψτε harmless sample data και αντικαταστήστε το container για να αποδείξετε ότι το συγκεκριμένο path είναι πράγματι persistent. Ελέγξτε το path αντικαθιστώντας το container όσο υπάρχουν harmless sample data· έτσι εντοπίζονται mounts που δείχνουν μία directory πιο πάνω ή πιο κάτω από το σωστό σημείο.

Στη συνέχεια δοκιμάστε το disaster recovery σε blank host. Όπου χρειάζεται, χρησιμοποιήστε application-consistent database export και επαληθεύστε ότι τα private tarballs, τα metadata, οι users και το config επανέρχονται και ότι το clean project εγκαθιστά το ίδιο package integrity. Ο οδηγός για database backups που έχουν δοκιμαστεί με restore προσφέρει ισχυρότερο στόχο από έναν απλό έλεγχο ότι δημιουργήθηκε ένα archive file.

Credentials, roles και exposed surfaces

Για το Verdaccio, η πολύτιμη επιφάνεια δεν είναι απαραίτητα η landing page. Το βασικό λάθος είναι να επιτρέπετε anonymous publish ή να χρησιμοποιείτε writable uplink configuration. Αντιμετωπίστε το σκόπιμα: απαγορεύστε το anonymous publish, ορίστε scopes για τους maintainers και διατηρήστε το npm authentication συνδεδεμένο με το ακριβές HTTPS registry host.

Το VERDACCIO_PUBLIC_URL είναι configuration και όχι secret· κρατήστε την τιμή του explicit, προστατεύοντας παράλληλα τα ξεχωριστά credentials που χρησιμοποιεί το Verdaccio. Χρησιμοποιήστε unprivileged container user όταν το image το υποστηρίζει και μην κάνετε mount άσχετα credentials. Εφαρμόστε rate ή size limits στο ingress, όπου untrusted work μπορεί να καταναλώσει tarball storage, metadata operations, concurrent installs και latency προς τα configured upstream registries.

Failure drills για το Verdaccio

Τα capacity tests πρέπει να ασκούν πίεση στο tarball storage, τις metadata operations, τα concurrent installs και το latency προς τα configured upstream registries, όχι να στέλνουν επαναλαμβανόμενα requests στο /. Εκτελέστε το σενάριο «συνδεθείτε με npm, δημοσιεύστε ένα scoped package, εγκαταστήστε το από ένα clean project και επιβεβαιώστε ότι ένα upstream package έχει γίνει cached» με ρεαλιστικό concurrency και καταγράψτε latency, error rate και storage growth.

Ο σχεδιασμός του upgrade πρέπει να λαμβάνει υπόψη αυτόν τον κίνδυνο: το config syntax, τα authentication plugins και τα package metadata πρέπει να δοκιμάζονται στη target major version του Verdaccio. Δοκιμάστε τη νέα release με representative input, επαναλάβετε το acceptance transaction και συγκρίνετε το αποτέλεσμα. Αν οι npm clients στέλνουν authentication σε διαφορετικό host ή το package storage είναι read-only, καταγράψτε το failing transaction και ελέγξτε το πρώτο boundary που εμπλέκεται, αντί να υποθέσετε ότι ευθύνεται το ingress.

Αποδείξτε τη λειτουργία του deployment του Verdaccio end to end

Μην χρησιμοποιείτε την κίνηση του πρώτου user ως acceptance test για το Verdaccio. Προετοιμάστε harmless sample state και εκτελέστε την πλήρη ενέργεια «συνδεθείτε με npm, δημοσιεύστε ένα scoped package, εγκαταστήστε το από ένα clean project και επιβεβαιώστε ότι ένα upstream package έχει γίνει cached». Καταγράψτε το ακριβές public URL, το result, το image reference και το log interval που σχετίζονται με την εκτέλεση.

Αντικαταστήστε το container και επαναλάβετε χωρίς να κάνετε rebuild τα data. Στη συνέχεια κάντε recovery σε άδειο host· η συνθήκη recovery είναι να επανέλθουν τα private tarballs, τα metadata, οι users και το config και το clean project να εγκαταστήσει το ίδιο package integrity. Παρατηρήστε το tarball storage, τις metadata operations, τα concurrent installs και το latency προς τα configured upstream registries σε κάθε pass και ορίστε ένα alert γύρω από την υποβάθμιση του transaction, όχι γύρω από idle container metrics.

Ένας τελευταίος έλεγχος πρέπει να αποτύχει σκόπιμα: αρνηθείτε προσωρινά στο test identity την πρόσβαση στο persistent configuration, το htpasswd storage και το προαιρετικό object storage. Επιβεβαιώστε ότι το μήνυμα του Verdaccio εντοπίζει το σχετικό boundary, αντί να προκαλεί διαγραφή δεδομένων ή endless restart. Επαναφέρετε τη σωστή συνθήκη και επιβεβαιώστε ότι το ίδιο sample transaction ολοκληρώνεται με επιτυχία. Κρατήστε αυτό το σύντομο drill στο release checklist.

Κρατήστε το Verdaccio explicit ενώ το Dockup χειρίζεται το routing

Για το Verdaccio, το Dockup μπορεί να δημιουργήσει το route και το TLS certificate, να διατηρήσει τα mounts, να παραδώσει secrets και να τοποθετήσει το persistent configuration, το htpasswd storage και το προαιρετικό object storage σε private networking, κάνοντας deployment είτε στο Dockup είτε σε attached servers.

Το release gate παραμένει το συγκεκριμένο Verdaccio transaction: συνδεθείτε με npm, δημοσιεύστε ένα scoped package, εγκαταστήστε το από ένα clean project και επιβεβαιώστε ότι ένα upstream package έχει γίνει cached. Επαληθεύστε επίσης τη συνθήκη restore — τα private tarballs, τα metadata, οι users και το config πρέπει να επανέλθουν και το clean project να εγκαταστήσει το ίδιο package integrity. Αυτοί οι δύο έλεγχοι δείχνουν αν το deployment λειτουργεί και αν μπορεί να ανακτηθεί.

Συχνές ερωτήσεις

Τι χρειάζεται το Verdaccio για deployment σε production;

Δρομολογήστε το Verdaccio container στο port 4873 μέσω ενός HTTPS origin. Το supporting network requirement είναι persistent configuration, htpasswd storage και προαιρετικό object storage. Μην θεωρήσετε το Verdaccio ready μέχρι να μπορείτε να συνδεθείτε με npm, να δημοσιεύσετε ένα scoped package, να το εγκαταστήσετε από ένα clean project και να επιβεβαιώσετε ότι ένα upstream package έχει γίνει cached.

Ποια δεδομένα του Verdaccio πρέπει να περιλαμβάνονται σε backup;

Κάντε persist το /verdaccio/storage και συμπεριλάβετε τα package tarballs, τα metadata, το config και τα authentication files στο ίδιο recovery manifest. Ένα clean Verdaccio restore θεωρείται επιτυχές μόνο όταν επανέλθουν τα private tarballs, τα metadata, οι users και το config και το clean project εγκαταστήσει το ίδιο package integrity.

Χρειάζεται το Verdaccio HTTPS πίσω από reverse proxy;

Χρησιμοποιήστε HTTPS για το public Verdaccio origin και κρατήστε το port 4873 στο internal route. Εφαρμόστε σωστά τη ρύθμιση του Verdaccio: ορίστε το public URL και το npm registry URL στο ίδιο HTTPS origin. Για το Verdaccio, το HTTPS προστατεύει τα credentials ή το user content κατά τη μεταφορά και διατηρεί συνεπή τη client behavior που εξαρτάται από το origin.

Πώς πρέπει να δοκιμάζεται ένα upgrade του Verdaccio;

Κάντε restore το τρέχον state του Verdaccio σε isolated deployment, εφαρμόστε την candidate version και επαναλάβετε το acceptance transaction. Δώστε ιδιαίτερη προσοχή, επειδή το config syntax, τα authentication plugins και τα package metadata πρέπει να δοκιμάζονται στη target major version του Verdaccio. Κρατήστε το προηγούμενο Verdaccio image μέχρι να κατανοήσετε το data-migration και το rollback boundary.