How to self host Verdaccio

verdaccio.md

Private Package Repositories

• npm.org Private Packages link
• Options for self-hosting private package repos link

Verdaccio

About Verdaccio link

Useful Commands

yarn config set registry http://localhost:4873
yarn config set registry https://npm.patrickgallagher.dev:443
# set back to normal
yarn config set registry https://registry.npmjs.com/
npm set registry https://registry.npmjs.com/

Install with docker-compose & Nginx

This guide is adapted from verdaccio/docker-examples. Feel free to use this resource to find examples that fit your needs.

Download the repo

git clone https://github.com/verdaccio/verdaccio.git ~/verdaccio

Configure it

First lets update the docker-compose.yaml to work with our setup.

cd ~/verdaccio && nano docker-compose.yaml

Replace it with the following:

version: '3.1'

services:
  verdaccio:
    restart: unless-stopped
    image: verdaccio/verdaccio:latest
    container_name: 'verdaccio'
    networks:
      - node-network
    environment:
      - VERDACCIO_PORT=4873
    ports:
      - '4873:4873'
    volumes:
      - './storage:/verdaccio/storage'
      - './config:/verdaccio/conf'
      - './plugins:/verdaccio/plugins'
networks:
  node-network:
    driver: bridge

Now we will use the example in /conf/docker.yaml to create our Verdaccio config file /config/config.yaml

mkdir -p ~/verdaccio/config && cp ~/verdaccio/conf/docker.yaml ~/verdaccio/config/config.yaml
nano ~/verdaccio/config/config.yaml

Run it

Start the docker container

docker-compose up -d

Check the Web UI

If using a remote server, create a tunnel to your local machine, otherwise skip this.

ssh -L 127.0.0.1:4873:127.0.0.1:4873 user@mysite.com

Now navigate in your browser to http://localhost:4873 and you should see the Verdaccio web UI.

Route with Nginx

Next we need to permanently expose port 4873 to the world. Create /etc/nginx/sites-enabled/verdaccio.conf with the following:

server {

  # NOTE: Using a path eg. mysite.com/npm is not recommended. It will cause headaches.
  # I recommend using a subdomain instead
  server_name npm.mysite.com; # CHANGE ME

  listen 80;
  listen [::]:80;
  access_log /var/log/nginx/verdaccio.log;
  charset utf-8;

  location / {
    proxy_pass http://127.0.0.1:4873/;
    proxy_set_header Host            $host:$server_port;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

Let's put the changes into effect:

sudo nginx -t
sudo systemctl reload nginx

Now we need Certbot to issue an SSL certificate for our server.

sudo certbot --nginx certonly
sudo systemctl reload nginx

Excellent your Verdaccio web UI is now accessible from https://npm.mysite.com

Restrict Access

You should always restrict at least publish access, otherwise anyone can spam your repository with junk.

You have two options for restricting access:

1. Authenticated users only: Use npm adduser command to add a new user with the $authenticated privilege.
2. Approvelist: Update config.yaml with a list of approved usernames

Regardless of which option you choose, first make sure you can authenticate successfully.

# Always use npm for login, even if you use yarn CLI
npm login

Option 1: Create a new Authenticated user

To get the $authenticated privilege, add yourself as a user to your registry.

npm adduser --registry https://npm.mysite.com

Things to pay attention to:

• Anyone can call this command against your registry to become $authenticated
• You'll likely want to use the max_users config to limit this to just a few people, and be sure to use all the available slots!

Option 2: Approvelist

Update your config.yaml file with the npm usernames you wish to use, and restart the container.

nano ~/verdaccion/config/config.yaml
cd ~/verdaccio && docker-compose down && docker-compose up -d

Using Verdaccio

We need to tell our local CLI tool, either yarn or npm, to use our private registry.

yarn config set registry https://npm.mysite.com:443
# OR
npm set registry https://npm.mysite.com:443

Now when we run npm install, it will look in our private registry first, before continuing to a fallback. If you ever want to set things back to normal you can use these commands:

yarn config set registry https://registry.npmjs.com/
# OR
npm set registry https://registry.npmjs.com/

Notes / Other

• I had to set always-auth=true on my local npm client. see link
• Don't forget the ":443" in the url, eg.g "https://npm.patrickgallagher.dev:443"
• Using a CI platform? See link for tips on authentication