{"id":1618,"date":"2026-11-06T07:35:38","date_gmt":"2026-11-06T07:35:38","guid":{"rendered":"https:\/\/virtualserversvps.com\/blog\/?p=1618"},"modified":"2026-11-06T07:35:38","modified_gmt":"2026-11-06T07:35:38","slug":"private-npm-registry-mirror-on-one-vps","status":"publish","type":"post","link":"https:\/\/virtualserversvps.com\/blog\/private-npm-registry-mirror-on-one-vps\/","title":{"rendered":"Private npm Registry Mirror on One VPS"},"content":{"rendered":"<p><strong>TL;DR \/ Summary:<\/strong> Small product teams can host a private npm-compatible registry or pull-through cache on one VPS to speed CI and keep internal packages off public scanners. Lock auth down, mirror only what you need, and measure cache hit rates before calling the project finished.<\/p>\n<h2>The pain that justifies another box<\/h2>\n<p>Public registry blips stall every pipeline at once. Internal packages published to a public scope invite curious downloads. A private registry on a virtual server fixes both problems when the team is still too small for a managed enterprise contract.<\/p>\n<p>You are buying control and latency, not a new religion. If a managed offering already fits the budget, take it. This guide assumes you chose self-host for clear reasons.<\/p>\n<h2>Registry vs pull-through cache<\/h2>\n<p>A full private registry stores your scoped packages and may proxy public ones. A pull-through cache mainly accelerates and pins public dependencies. Many teams need both behaviors; some only need the cache.<\/p>\n<p>Decide which problem hurt last quarter. Do not install features for imaginary future monorepos.<\/p>\n<ul>\n<li>Internal libraries \u2192 private registry with auth<\/li>\n<li>Flaky public downloads in CI \u2192 cache<\/li>\n<li>Both \u2192 registry that can uplink carefully<\/li>\n<\/ul>\n<h2>VPS placement and TLS<\/h2>\n<p>Put the VPS in the region nearest your CI runners. Enable TLS with a real certificate. Package managers will talk to this host thousands of times a day; browsers are not the only clients that deserve HTTPS.<\/p>\n<p>Firewall so only office egress IPs and CI IPs can reach the service ports. The public internet does not need to browse your package list.<\/p>\n<blockquote><p>If anonymous read is on, assume the world will read.<\/p><\/blockquote>\n<h2>Authentication that survives employee churn<\/h2>\n<p>Use token auth per machine user, not a shared password in a wiki. Rotate tokens when people leave. Store publish tokens only on the CI role that is allowed to publish.<\/p>\n<p>Developers can read with narrower tokens. Publish should be boring and rare.<\/p>\n<h2>Storage growth plans<\/h2>\n<p>Package tarballs accumulate. Mount a dedicated volume, monitor inode and byte usage, and set retention for unused cached public packages. Internal release history may need longer retention \u2014 decide explicitly.<\/p>\n<p>Snapshots weekly are cheap insurance against a bad upgrade of the registry software.<\/p>\n<h3>Backup is not the same as cache<\/h3>\n<p>You can rebuild a public cache. You cannot shrug away lost private tarballs of a hotfix from Tuesday. Back up private storage first.<\/p>\n<h2>Client configuration without tribal knowledge<\/h2>\n<p>Ship a short internal doc: registry URL, scope mapping, and how to request a token. Add a template <code>.npmrc<\/code> fragment to the eng handbook.<\/p>\n<p>If onboarding still requires a DM to the one person who \u201cknows Verdaccio,\u201d the project is incomplete.<\/p>\n<h2>Measuring whether it worked<\/h2>\n<p>Track cache hit ratio, p95 download time in CI, and disk growth weekly. If hit ratio stays low, your uplink rules or CI cold starts need attention \u2014 not a bigger VPS.<\/p>\n<p>If disk growth is linear and steep, retention is wrong.<\/p>\n<h2>Upgrade discipline<\/h2>\n<p>Pin the registry image version. Test upgrades on a snapshot-restored twin when possible. Read changelogs for auth breaking changes before you click update on Friday.<\/p>\n<p>Keep a rollback command in the README. Future you is a person.<\/p>\n<p>When you outgrow a single node, revisit managed options or a tiny active-passive pair. Until then, one well-run VPS beats three neglected ones. A clear overview of <a href=\"https:\/\/virtualserversvps.com\/\">VPS hosting<\/a> helps you re-shop CPU and disk without rewriting the app.<\/p>\n<h2>Publish workflow that prevents \u201claptop releases\u201d<\/h2>\n<p>Forbid publishing from developer laptops once CI publish works. Laptop releases skip logs and produce packages nobody can reproduce. The registry should accept publish tokens only from the CI egress IPs when your firewall can express that.<\/p>\n<p>Add a chat notification on every publish with package name, version, and pipeline link. Silent publishes are how surprise breakages travel.<\/p>\n<h2>Read-only mirrors for contractors<\/h2>\n<p>Contractors often need install access without publish rights. Issue short-lived read tokens and revoke them on contract end dates already in the calendar. Do not share the internal publish token \u201cjust for this afternoon.\u201d<\/p>\n<p>If contractors must be off-VPN, put the registry behind SSO-aware access rather than opening the world.<\/p>\n<h2>Package provenance notes for audits<\/h2>\n<p>Keep a lightweight provenance log: who published, which pipeline, which git SHA. When a dependency CVE appears, you need minutes-to-answer, not archaeology. Store the log off the registry disk as well as on it.<\/p>\n<p>If your registry software supports signed metadata, turn it on after a staging test. Unsigned internal packages become a trust story you cannot tell customers.<\/p>\n<h2>Rate limits and CI stampedes<\/h2>\n<p>Monday mornings can stampede the mirror when every laptop and runner refresh locks. Set rate limits that shed load gracefully and teach developers to use project-local caches. A mirror that melts weekly is worse than no mirror.<\/p>\n<p>Stagger scheduled dependency refresh jobs across the hour.<\/p>\n<p>When the mirror returns 429s, document the client backoff you expect in the eng handbook so every language ecosystem does not invent a different retry storm.<\/p>\n<h2>Sunset conditions<\/h2>\n<p>Write down what success looks like and what triggers migration: team size, compliance needs, or multi-region latency. Predetermined exits keep the registry from becoming an unpaid second product.<\/p>\n<p>Done carefully, a private registry VPS is boring infrastructure \u2014 the highest compliment in packaging.<\/p>\n<h2>Upstream outages and stale tarball risks<\/h2>\n<p>A mirror that keeps serving last week\u2019s tarball during an upstream outage can be useful\u2014or dangerous\u2014if a yanked package remains available. Decide in advance whether the mirror should fail closed on known yanks.<\/p>\n<p>Log package name, version, and fetch time for every cache fill. When security asks \u201cwhen did we pull that,\u201d the answer should not depend on memory.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>TL;DR \/ Summary: Small product teams can host a private npm-compatible registry or pull-through cache on one VPS to speed CI and keep internal packages off public scanners. Lock auth&#8230;<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"iawp_total_views":0,"footnotes":""},"categories":[9],"tags":[],"class_list":["post-1618","post","type-post","status-publish","format-standard","hentry","category-vps-hosting-tutorials"],"yoast_head":"<!-- This site is optimized with the Yoast SEO Premium plugin v26.1 (Yoast SEO v26.1) - https:\/\/yoast.com\/wordpress\/plugins\/seo\/ -->\n<title>Private npm Registry Mirror on One VPS - Virtual Servers VPS Blog<\/title>\n<meta name=\"description\" content=\"TL;DR \/ Summary: Small product teams can host a private npm-compatible registry or pull-through cache on one VPS to speed CI and keep internal packages\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/virtualserversvps.com\/blog\/private-npm-registry-mirror-on-one-vps\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Private npm Registry Mirror on One VPS\" \/>\n<meta property=\"og:description\" content=\"Private npm Registry Mirror on One VPS\" \/>\n<meta property=\"og:url\" content=\"https:\/\/virtualserversvps.com\/blog\/private-npm-registry-mirror-on-one-vps\/\" \/>\n<meta property=\"og:site_name\" content=\"Virtual Servers VPS Blog\" \/>\n<meta property=\"article:published_time\" content=\"2026-11-06T07:35:38+00:00\" \/>\n<meta name=\"author\" content=\"Virtual-Servers-Vps-Editor\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"Virtual-Servers-Vps-Editor\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"5 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/virtualserversvps.com\/blog\/private-npm-registry-mirror-on-one-vps\/\",\"url\":\"https:\/\/virtualserversvps.com\/blog\/private-npm-registry-mirror-on-one-vps\/\",\"name\":\"Private npm Registry Mirror on One VPS - Virtual Servers VPS Blog\",\"isPartOf\":{\"@id\":\"https:\/\/virtualserversvps.com\/blog\/#website\"},\"datePublished\":\"2026-11-06T07:35:38+00:00\",\"author\":{\"@id\":\"https:\/\/virtualserversvps.com\/blog\/#\/schema\/person\/82a299a8284a66ff49f97c74684724a0\"},\"description\":\"TL;DR \/ Summary: Small product teams can host a private npm-compatible registry or pull-through cache on one VPS to speed CI and keep internal packages\",\"breadcrumb\":{\"@id\":\"https:\/\/virtualserversvps.com\/blog\/private-npm-registry-mirror-on-one-vps\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/virtualserversvps.com\/blog\/private-npm-registry-mirror-on-one-vps\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/virtualserversvps.com\/blog\/private-npm-registry-mirror-on-one-vps\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/virtualserversvps.com\/blog\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Private npm Registry Mirror on One VPS\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/virtualserversvps.com\/blog\/#website\",\"url\":\"https:\/\/virtualserversvps.com\/blog\/\",\"name\":\"Virtual Servers VPS Blog\",\"description\":\"\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/virtualserversvps.com\/blog\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"},{\"@type\":\"Person\",\"@id\":\"https:\/\/virtualserversvps.com\/blog\/#\/schema\/person\/82a299a8284a66ff49f97c74684724a0\",\"name\":\"Virtual-Servers-Vps-Editor\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/virtualserversvps.com\/blog\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/d820b15f1cd028e97610d9adf536df7be5cb6423869967037d468d5355fa003f?s=96&d=mm&r=g\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/d820b15f1cd028e97610d9adf536df7be5cb6423869967037d468d5355fa003f?s=96&d=mm&r=g\",\"caption\":\"Virtual-Servers-Vps-Editor\"},\"sameAs\":[\"https:\/\/virtualserversvps.com\/blog\"],\"url\":\"https:\/\/virtualserversvps.com\/blog\/author\/virtualserversvps\/\"}]}<\/script>\n<!-- \/ Yoast SEO Premium plugin. -->","yoast_head_json":{"title":"Private npm Registry Mirror on One VPS - Virtual Servers VPS Blog","description":"TL;DR \/ Summary: Small product teams can host a private npm-compatible registry or pull-through cache on one VPS to speed CI and keep internal packages","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/virtualserversvps.com\/blog\/private-npm-registry-mirror-on-one-vps\/","og_locale":"en_US","og_type":"article","og_title":"Private npm Registry Mirror on One VPS","og_description":"Private npm Registry Mirror on One VPS","og_url":"https:\/\/virtualserversvps.com\/blog\/private-npm-registry-mirror-on-one-vps\/","og_site_name":"Virtual Servers VPS Blog","article_published_time":"2026-11-06T07:35:38+00:00","author":"Virtual-Servers-Vps-Editor","twitter_card":"summary_large_image","twitter_misc":{"Written by":"Virtual-Servers-Vps-Editor","Est. reading time":"5 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/virtualserversvps.com\/blog\/private-npm-registry-mirror-on-one-vps\/","url":"https:\/\/virtualserversvps.com\/blog\/private-npm-registry-mirror-on-one-vps\/","name":"Private npm Registry Mirror on One VPS - Virtual Servers VPS Blog","isPartOf":{"@id":"https:\/\/virtualserversvps.com\/blog\/#website"},"datePublished":"2026-11-06T07:35:38+00:00","author":{"@id":"https:\/\/virtualserversvps.com\/blog\/#\/schema\/person\/82a299a8284a66ff49f97c74684724a0"},"description":"TL;DR \/ Summary: Small product teams can host a private npm-compatible registry or pull-through cache on one VPS to speed CI and keep internal packages","breadcrumb":{"@id":"https:\/\/virtualserversvps.com\/blog\/private-npm-registry-mirror-on-one-vps\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/virtualserversvps.com\/blog\/private-npm-registry-mirror-on-one-vps\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/virtualserversvps.com\/blog\/private-npm-registry-mirror-on-one-vps\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/virtualserversvps.com\/blog\/"},{"@type":"ListItem","position":2,"name":"Private npm Registry Mirror on One VPS"}]},{"@type":"WebSite","@id":"https:\/\/virtualserversvps.com\/blog\/#website","url":"https:\/\/virtualserversvps.com\/blog\/","name":"Virtual Servers VPS Blog","description":"","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/virtualserversvps.com\/blog\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"},{"@type":"Person","@id":"https:\/\/virtualserversvps.com\/blog\/#\/schema\/person\/82a299a8284a66ff49f97c74684724a0","name":"Virtual-Servers-Vps-Editor","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/virtualserversvps.com\/blog\/#\/schema\/person\/image\/","url":"https:\/\/secure.gravatar.com\/avatar\/d820b15f1cd028e97610d9adf536df7be5cb6423869967037d468d5355fa003f?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/d820b15f1cd028e97610d9adf536df7be5cb6423869967037d468d5355fa003f?s=96&d=mm&r=g","caption":"Virtual-Servers-Vps-Editor"},"sameAs":["https:\/\/virtualserversvps.com\/blog"],"url":"https:\/\/virtualserversvps.com\/blog\/author\/virtualserversvps\/"}]}},"_links":{"self":[{"href":"https:\/\/virtualserversvps.com\/blog\/wp-json\/wp\/v2\/posts\/1618","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/virtualserversvps.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/virtualserversvps.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/virtualserversvps.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/virtualserversvps.com\/blog\/wp-json\/wp\/v2\/comments?post=1618"}],"version-history":[{"count":1,"href":"https:\/\/virtualserversvps.com\/blog\/wp-json\/wp\/v2\/posts\/1618\/revisions"}],"predecessor-version":[{"id":1619,"href":"https:\/\/virtualserversvps.com\/blog\/wp-json\/wp\/v2\/posts\/1618\/revisions\/1619"}],"wp:attachment":[{"href":"https:\/\/virtualserversvps.com\/blog\/wp-json\/wp\/v2\/media?parent=1618"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/virtualserversvps.com\/blog\/wp-json\/wp\/v2\/categories?post=1618"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/virtualserversvps.com\/blog\/wp-json\/wp\/v2\/tags?post=1618"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}