Skip to main content

Private NPM Registry Setup Guide

This guide covers how to:

  • Set up a Private NPM Registry using Verdaccio and Docker
  • Log in to your Private NPM Registry
  • Publish a Package
  • Download a Package
  • Grant Download Access to Specific Users
  • Restrict Anonymous Registrations and Manually Manage Users
  • Point Scoped Packages to Your Private NPM Registry

1. Setting Up Verdaccio with Docker​

Project Structure​

Create a directory named private-npm-registry (or any name you prefer):

private-npm-registry/
  conf/
    config.yaml
  storage/
  docker-compose.yml
  • config.yaml: Verdaccio configuration file
  • storage/: Holds published packages
  • docker-compose.yml: Docker configuration to launch Verdaccio

Configuring Verdaccio​

Create conf/config.yaml with the following:

storage: /verdaccio/storage

auth:
  htpasswd:
    file: ./htpasswd
    algorithm: bcrypt

packages:
  "@my-scope/*":
    access: $all
    publish: $authenticated

log:
  type: stdout
  format: pretty
  level: http

Notes:

  • $all → Anyone can download packages
  • $authenticated → Only logged-in users can publish
  • The registry hosts only packages under the @my-scope/* namespace (customize as needed)
caution

Verdaccio requires config.yaml, not config.yml.
See Verdaccio Config Docs for more options.

Docker Compose Configuration​

Create docker-compose.yml:

version: "3.8"

services:
  verdaccio:
    image: verdaccio/verdaccio:latest
    ports:
      - 4873:4873
    volumes:
      - ./conf:/verdaccio/conf
      - ./storage:/verdaccio/storage

This setup:

  • Uses the latest Verdaccio Docker image
  • Exposes port 4873
  • Persists data using mounted volumes

Starting Your Registry​

From the project root:

docker compose up

Your private NPM registry is now running at http://localhost:4873.

2. Logging In​

Log in to your registry:

npm login --registry http://localhost:4873
  • You’ll be prompted for a username and password.
  • The first login automatically registers a new account.
  • Credentials are stored in your ~/.npmrc file.
    (Optional: create a project-specific .npmrc.)

Helpful commands:

npm whoami --registry http://localhost:4873
npm logout --registry http://localhost:4873

3. Publishing a Package​

To test publishing, create a sample package.

Steps​

  1. Create and enter a folder:

    mkdir hello-world && cd hello-world

  2. Initialize the project:

    npm init

    Name the package @my-scope/hello-world.

  3. Add an index.js file:

    module.exports = function () {
      console.log("Hello World! From @my-scope/hello-world");
    };

  4. Publish your package:

    npm publish --registry http://localhost:4873

You’ve successfully published your first private package.

4. Downloading a Package​

Install from your registry:

npm install @my-scope/hello-world --registry http://localhost:4873

By default, $all users can download this package.
To restrict access, modify the config as shown below.

5. Granting Access to Specific Users​

Update conf/config.yaml with a package-specific rule:

packages:
  "@my-scope/private-*":
    access: admin user-a user-b
    publish: admin
  • admin → Can publish and download
  • user-a, user-b → Can download only
  • Others → No access

Built-in Groups:

GroupDescription
$allAnyone, including anonymous users
$authenticatedLogged-in users only

Verdaccio does not support custom groups. You must list users explicitly.
See this Stack Overflow reference for more details.

6. Restricting Anonymous Registrations​

To disable public signups and manually manage accounts, modify auth in config.yaml:

auth:
  htpasswd:
    file: ./htpasswd
    algorithm: bcrypt
    max_users: -1

Then, manually create users by generating encrypted credentials using a tool like:
HTPasswd Generator

Copy the generated output into conf/htpasswd.

7. Scoped Packages Configuration​

To have your NPM client automatically use your registry for scoped packages, add to your ~/.npmrc:

; @my-scope scoped packages should use this registry
@my-scope:registry = http://localhost:4873

This allows you to run:

npm install @my-scope/hello-world

—without specifying the --registry flag each time.

8. Next Steps​

Congratulations — your private NPM registry is up and running!
Future improvements may include:

Resources​