How To Set Up a Private npm Registry on Ubuntu 26.04

Verdaccio is a lightweight, open source private npm registry that lets you host, publish, and manage your own Node.js packages on your own server. It can also proxy and cache packages from the public npm registry, making package management faster and more reliable for development teams.

If your team builds private Node.js packages, hosting your own npm registry gives you complete control over package publishing and distribution. Instead of publishing packages to the public npm registry, you can keep everything on your own server while still using public packages whenever needed.

Prerequisites

Before getting started, make sure you have:

A dedicated server running Ubuntu 26.04
A user with sudo privileges
A domain or subdomain pointing to your server (for example npm.example.com)
Port 80 and 443 open in your firewall

Step 1. Update the Server

Update your package list and install the latest available updates.

sudo apt update
sudo apt upgrade -y

Step 2. Install Node.js 24 LTS

Verdaccio requires Node.js. This guide uses the latest Node.js 24 LTS release.

Add the NodeSource repository.

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -

Install Node.js.

sudo apt install -y nodejs

Verify the installation.

node -v
npm -v

You should see the installed Node.js and npm versions.

Step 3. Install Verdaccio

Install Verdaccio globally using npm.

sudo npm install -g verdaccio

Confirm the installation.

verdaccio --version

Step 4. Create a Dedicated User

Create a dedicated user for the Verdaccio service.

sudo useradd --system --create-home --shell /bin/bash verdaccio

Create the directories that Verdaccio will use.

sudo mkdir -p /opt/verdaccio/
sudo mkdir -p /opt/verdaccio/storage
sudo mkdir -p /opt/verdaccio/plugins

Assign the correct ownership.

sudo chown -R verdaccio:verdaccio /opt/verdaccio

Step 5. Generate the Default Configuration

Switch to the new user.

sudo -iu verdaccio

Run Verdaccio once.

verdaccio

Press:

Ctrl + C

Copy the generated configuration:

cp ~/verdaccio/config.yaml /opt/verdaccio/config.yaml
exit

Step 6. Create a Systemd Service

Create a new systemd service.

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

Add the following configuration.

[Unit]
Description=Verdaccio Private npm Registry
After=network.target

[Service]
Type=simple
User=verdaccio
Group=verdaccio
WorkingDirectory=/opt/verdaccio
ExecStart=/usr/bin/verdaccio --config /opt/verdaccio/config.yaml
Restart=always

[Install]
WantedBy=multi-user.target

Reload systemd.

sudo systemctl daemon-reload

Start and Enable the service.

sudo systemctl enable --now verdaccio

Verify the service.

sudo systemctl status verdaccio

The service should display an active (running) status.

Step 7. Install Nginx

Install Nginx.

sudo apt install nginx -y

Start and enable the service.

sudo systemctl enable --now nginx

Verify that Nginx is running.

sudo systemctl status nginx

Add HTTP and HTTPS ports in the firewall

sudo ufw allow 80,443/tcp
sudo ufw reload

Step 8. Create an Nginx Reverse Proxy

Create a new Nginx configuration.

sudo nano /etc/nginx/sites-available/npm.example.com

Replace npm.example.com with your own domain and paste the following configuration.

server {
    listen 80;
    listen [::]:80;

    server_name npm.example.com;

    client_max_body_size 100M;

    location / {
        proxy_pass http://localhost:4873;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
    }
}

Enable the site.

sudo ln -s /etc/nginx/sites-available/npm.example.com /etc/nginx/sites-enabled/

Test the configuration.

sudo nginx -t

If the configuration is valid, reload Nginx.

sudo systemctl reload nginx

You should see the Verdaccio web interface.

Step 9. Install a Let's Encrypt SSL Certificate

Install Certbot and the Nginx plugin.

sudo apt install certbot python3-certbot-nginx -y

Request an SSL certificate.

sudo certbot --nginx -d npm.example.com

Follow the prompts and enter your email address when requested.

After the certificate is installed, open:

https://npm.example.com

You should now see the Verdaccio interface over HTTPS.

Step 10. Configure npm to Use Your Private Registry

Now that your registry is available over HTTPS, configure npm to use your domain.

npm set registry https://npm.example.com

Replace npm.example.com with your own domain.

Verify the configured registry.

npm config get registry

Expected output:

https://npm.example.com/

Step 11. Create Your First User

Verdaccio uses authentication for publishing packages. Create your first user with the following command.

npm login --registry https://npm.example.com --auth-type=legacy

When prompted, enter:

Username
Password
Email address

After a successful login, npm stores your authentication token locally and you're ready to publish packages.

Step 12. Create Your First Package

Create a new project directory.

mkdir hostnextra-package && cd hostnextra-package

Initialize a new npm package.

npm init -y

Create a simple JavaScript file.

echo "module.exports = () => console.log('Hello from private registry');" > index.js

Open the package configuration.

nano package.json

Update the name field to something unique.

{
  "name": "@company/hostnextra-package",
  "version": "1.0.0",
  "description": "Sample package",
  "main": "index.js",
  "author": "",
  "license": "ISC"
}

Using a scoped package name such as @company/hostnextra-package helps organize private packages and avoids name conflicts.

Step 13. Publish the Package

Publish the package to your private registry.

npm publish

Since you've already configured npm to use your private registry, there is no need to specify the registry URL every time.

Refresh the Verdaccio web interface.

https://npm.example.com

Your package should now appear in the package list.

Step 14. Install Packages from Your Registry

You can now install this package normally using following command:

npm install @company/hostnextra-package

If you are trying from your local machine, first you need to change the npm registry using following command:

npm set registry https://npm.example.com
npm adduser --registry https://npm.example.com/
npm profile set password --registry https://npm.example.com/

Now you can try to install the package again.

Update an Existing Package

npm does not allow publishing the same version twice.

For example, if version 1.0.0 has already been published, attempting to publish it again returns a 409 Conflict error.

Increase the package version before publishing an update.

npm version patch

This updates the version from:

1.0.0

to:

1.0.1

Publish the updated version.

npm publish

You can also use:

npm version minor

npm version major

depending on the type of release.

Conclusion

In this tutorial we have learned how to set up a private npm registry on Ubuntu 26.04 using Verdaccio.

You now have a fully functional private npm registry running on Ubuntu 26.04 with Verdaccio, Nginx, and Let's Encrypt SSL. Your team can publish private packages, install them securely over HTTPS, and continue using public npm packages through Verdaccio's built in proxy.

This setup is lightweight, easy to maintain, and works well for personal projects, development teams, and organizations that want to manage their own npm packages from a central location.