This page looks best with JavaScript enabled

Verdaccio, Synology, and Unity. Oh My!

 ·  ☕ 7 min read

Setting up a private Verdaccio registry is generally quite easy, and there are plenty of tutorials and videos covering its setup. Unfortunately, most of those resources focus on setting up Verdaccio on a local system, and when docker is involved the tutorials usually assume docker is being run from the command line.

Running docker containers on a Synology NAS is a completely different process, and I wasn’t able to find even a single resource that covered the procedure. This post will hopefully clear some things up.

Docker

First things first, you’ll need to install the Docker package if it’s not already installed.

  1. Open Synology Package Center.

  2. Search for docker, select it, and click Install.

Folder Setup

When working with Docker containers, I try to handle them like read-only objects whenever possible. If the container needs to work with persistent data, that data should be stored outside the container.

It’s common for containers to provide “mount paths” that can be used to map file system folders to the container. The container will then store data in those mapped folders. Later, if you decide to update or replace the container, the persistent data will remain in these folders.

The Verdaccio container exposes three mount paths (conf, plugins, and storage), and we’re going to set those folders up first, so that they’re ready to use when Verdaccio is configured later.

  1. Create a Shared Folder called docker. It’s assumed you’ve already created shared folders on your NAS and know how it’s done.

    Consider using the following configuration options:

    • Disable: Advanced Permissions, Recycle Bin, and File Compression.
    • Enable: Data Integrity Protection.
  2. Using File Station, create the following folder hierarchy, which will be used by the container:

    
     docker
      
     verdaccio
        
     conf
        
     plugins
        
     storage
    

Download Verdaccio

Download the latest 5.x container, which as of 2022-03-01 is 5.6.2.

  1. Open Docker and go to the Registry tab.

  2. Search for verdaccio/verdaccio, select it, and click Download.
    Verdaccio Container

  3. Select 5 from the Please Choose a Tag dropdown and click Select.

Install Verdaccio

  1. In Docker, go to the Image tab.

  2. Launch verdaccio/verdaccio:5 image with the following settings:

    • Change the Container Name name, as desired. The default name is verdaccio-verdaccio.
    • Check Enable resource limitation, if you want to control how much memory the container will use. My NAS has 8 GB of RAM, so I set the Memory Limit to 2048 MB.
      Verdaccio Settings
  3. Click Advanced Settings and go to the Advanced Settings tab, if it’s not already selected.

    • Check Enable auto-restart so that the container will restart after an improper shutdown.
      Verdaccio Advanced Settings
  4. Go to the Volume tab.

    • For each of the three folders created earlier, click Add Folder, select the folder, and enter the Mount Path.
      Verdaccio Volume
  5. Go to the Port Settings tab.

    • Change the Local Port to match the Container Port value, which in this case is 4873.
      Verdaccio Port Settings
  6. Click Apply, then Next, and finally Apply.

Run Verdaccio

The container should automatically start after applying settings. You can Start, Stop, and Restart it from the Container tab in Docker.

Verdaccio has a web user interface to display packages in the registry.
The web interface can be accessed at http://<nas_ip_address>:4873/.

Terminal Commands

The npm executable provides command line access to the registry, and it allows you to add users, login, logout, set the target registry, publish packages, and more.

Many commands accept an option to target the registry, such as:
npm adduser --registry http://<nas_ip_address>:4873/

You can also set the registry so that it’s automatically used when executing future commands.

// Sets the registry (storing it in <home_folder>/.npmrc)
npm set registry=http://<nas_ip_address>:4873/

// You can now add a user to the registry with out specifying it.
npm adduser

// Get the current registry
npm get registry
> http://<nas_ip_address>:4873/

Some Useful Commands

ping
Ping npm registry
login
Create or verify a user account.
publish
Publish a package
whoami
Display the username that’s currently logged in.
help
Get help on npm. This will open a webpage with details on the selected command.

Authentication

The basic Verdaccio setup uses htpasswd for authentication.

Based on config.yaml the file should probably be called htpasswd and not the more common .htpasswd.

You can use a Linux command line program create an htpasswd file, otherwise try this:

  1. Generate a username:password-hash string using an online htpasswd generator. Only the “Apache specific salted MD5 (insecure by common)” mode worked for me. Your mileage may vary. It should look similar to this:
    username:$apr1$wzmb709f$fqeK6wasto.rEa6RhtaMj0

  2. Create a htpasswd file inside the verdaccio/storage/ folder.

  3. In that file paste the generated htpasswd string, then save the file.

  4. You should now be able to log in to your registry from the command line using npm login.

Authentication Plugins

There are more than a dozen other authentication plugins offered by the Verdaccio community, and some of them look pretty cool.

In the near future, I intend to try the Verdaccio GitHub OAuth plugin, which offers GitHub OAuth integration for both the browser and the command line. Login can be limited to members of a certain GitHub organizations, and package access can be limited to GitHub organizations, teams, repos, and users. If I switch over to it, I’ll update this post with details.

Publishing Errors

If, when publishing a package in the registry, you receive an error, such as “404 Not Found” or “no such package available”, the problem could be related to folder ownership.

By default, the conf, plugins, and storage folders are owned by the NAS user that created them, however from what I’ve read in some bug reports (#483, #1085), the storage folder and possibly all three should have the owner set to verdaccio or, more importantly, to the UID of 10001.

I received these errors myself, and changing the owner seemed to solve the problem.

Now changing the owner of a folder or file to another registered user in Synology DSM is pretty straight forward, but changing it to an unknown user or specific UID is not. For that, I believe you need to SSH into the NAS and change it manually from the command line. That’s what I did.

SSH

If you’re like me, you probably don’t have SSH enabled under normal circumstances, so you’ll have to temporarily enable it until the folder ownership has changed.

To log into the DSM via SSH:

  1. Enable SSH via DSM Control Panel > Terminal & SNMP > Enable SSH service.

    Terminal & SNMP

  2. From the Windows Terminal command line:

    ssh <admin_account>@<ip_address>

    So, if the admin user is “bob” and the NAS IP address is “192.168.1.150”, you’d use:

    ssh bob@192.168.1.150

  3. Enter the account’s password when prompted.

  4. You’ll likely start in the user’s home folder, so change to the verdaccio folder created earlier with something like:

    cd /volume1/docker/verdaccio/

  5. You can view the folder owners using ls -l. The third column will list the folder owner.

  6. Change the owner of each folder using sudo and chown.

    sudo chown 10001 storage/
    sudo chown 10001 plugins/
    sudo chown 10001 conf/
    
  7. Verify that folder ownership has changed then then logout with exit.

  8. Disable SSH again via DSM Control Panel > Terminal & SNMP > Enable SSH service.

Unity Scoped Registry Setup

The Unity manual covers Scoped Registries and Scoped Registry Authentication, and many other sites provide similar information on how to configure a Unity project to connect to a scoped registry.

I’ll elaborate on the process later, if necessary.

Share on
Support the author with

Michael Ryan
Michael Ryan
<div><span>Video game developer</span> /<br /><span>Retro computing fanatic</span></div>