Verdaccio - NPM Mirror

What is Verdaccio?

Verdaccio is a lightweight private NPM proxy registry that is useful for caching NPM packages. It is a self-hosted NPM registry that can be used to cache NPM packages locally.

Installation

Before installing Verdaccio, you need to have Node.js installed on your system. You can install Node.js here.

Ubuntu Server

> npm install -g verdaccio

Start Verdaccio

Switch to the directory where you want to store the NPM packages. Then run the following command:

> verdaccio

This command will create verdaccio folder with config file and storage folder.

Configuration

Edit the config.yaml file in the verdaccio folder.

storage: ./storage

web:
  enable: false
  
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    
packages:
  "@*/*":
    access: $all
    publish: $authenticated
    proxy: npmjs
  "**":
    access: $all
    publish: $authenticated
    proxy: npmjs
    
logs:
  - {type: stdout, format: pretty, level: info}

Service

Create a service to run Verdaccio as a daemon.

> sudo nano /etc/systemd/system/verdaccio.service

Add the following content to the file if you are using NVM:

[Unit]
Description=Verdaccio - Lightweight private npm proxy registry
After=network.target

[Service]
Type=simple
User=ubuntu
ExecStart=/home/ubuntu/.nvm/versions/node/v22.12.0/bin/node /home/ubuntu/.nvm/versions/node/v22.12.0/bin/verdaccio  --config /data/verdaccio/config.yaml
Restart=on-failure
WorkingDirectory=/data

[Install]
WantedBy=multi-user.target

Reload daemon:

> sudo systemctl daemon-reload

Enable service

> sudo systemctl enable verdaccio

Start the service:

> sudo systemctl start verdaccio

Secure Verdaccio with SSL

Certbot

Install Certbot:

> sudo apt update
> sudo apt install certbot

Retrieve a domain certificate:

> sudo certbot certonly --standalone -d npm.example.com

Automate renewal:

> sudo crontab -e

Add the following line to the cron file:

0 0 * * * certbot renew --quiet

Generate Diffie-Hellman Key

Generate dhpam.pem file:

> openssl dhparam -out /etc/ssl/dhparam.pem 2048

Nginx Reverse Proxy

Create a new Nginx configuration file:

> sudo nano /etc/nginx/sites-available/verdaccio

Add the following content to the file:

server {
    listen 80 default_server;
	listen [::]:80 default_server;
    server_name npm.example.com;

    location / {
        proxy_pass http://127.0.0.1:4873;
        proxy_read_timeout 90;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

server {
    listen 443 ssl;
    server_name npm.example.com;

    ssl_certificate /etc/letsencrypt/live/npm.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/npm.example.com/privkey.pem;
    ssl_dhparam /etc/ssl/dhparam.pem;
    
    # Define the access log location and format
    access_log /data/logs/nginx/npm.example.access.log combined;
    error_log /data/logs/nginx/npm.example.error.log;

    location / {
        proxy_pass http://localhost:4873;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme; # Important
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Enable the site:

> sudo ln -s /etc/nginx/sites-available/verdaccio /etc/nginx/sites-enabled/

Reload Nginx:

> sudo systemctl reload nginx

NPM Configuration

Option 1:

To use Verdaccio as a mirror, you need to set the registry to the Verdaccio server.

> npm set registry https://npm.example.com
# or
> npm config set registry https://npm.example.com

To reset to the default registry:

> npm set registry https://registry.npmjs.org/

Option 2:

You can also use the --registry option to install packages from a custom registry.

> npm install <package-name> --registry=https://npm.example.com

Option 3:

You can also set the registry in the .npmrc file.

registry=https://npm.example.com