Skip to content


Created: 2018-10-16 08:49:19 -0700 Modified: 2019-03-28 21:35:03 -0700

Verdaccio is the successor to Sinopia. It provides a private NPM registry that you can host yourself.

Basics of using with Yarn:

  • Point Yarn at the registry: yarn config set @foo:registry =URL
  • Authenticate: npm adduser –registry=URL
  • Make sure it worked: yarn info @foo/package


  • Docker setup (reference)
    • docker pull <name of image>
    • Then, in order to specify the “-v” to bind to the host operating system, you need to set permissions for the verdaccio directory. The command on their page isn’t exactly right, so since it didn’t work after that, I just read about how to use Docker volumes.
      • docker run -it —rm —name verdaccio -p 4873:4873 —mount source=myvol2,target=/verdaccio/conf —mount source=myvol2,target=/verdaccio/storage —mount source=myvol2,target=/verdaccio/plugins verdaccio/verdaccio

For some clarification, here’s the scenario that I’m talking about:

  • Verdaccio hosts a bunch of @botland modules which are private and only hosted here.
  • Verdaccio passes through to the main NPM registry for any public modules, e.g. lodash.

Because containers are short-lived, restarting the Verdaccio container will wipe out all @botland modules and require a republish. This points to the need for persistent storage for any private modules. As for public modules, I plan on setting up my NPM/Yarn registries such that I use the official NPM repository for those. Note that only developers and CI should be hitting either registry in the first place; something like a game server will be launched from a container, and the container would be built by a developer or CI.

If, for whatever reason, I wanted Verdaccio to fetch public NPM repos but not cache them, I can turn caching off (reference).

Verdaccio can be configured to use AWS S3 for storage (reference). The library uses AWS’s Node SDK, meaning they read your credentials from your home directory, which means they need to be accessible. On AWS itself, the container agent will put them there, but you can’t have via ECS_AWSVPC_BLOCK_IMDS. Outside of AWS, you’ll run into a problem where developers without access to AWS credentials would be unable to run Verdaccio (not that they’d probably even need to). There are some ways to address this:

  • Make a new IAM role that just allows access to a particular S3 bucket.
  • Specify a separate config.yaml so that you have a local version with ephemeral storage and a production version that uses AWS.
  • Don’t allow developers to run the container without the credentials and copy the credentials over as a mount point or a volume.

For my use-case, I decided to just only let this work on AWS and not even mount the credentials in a volume. I figured it’s easy enough to switch in the future, and we don’t have much of a reason to even run Verdaccio locally.

As for the actual steps that I had to do:

  • Use the S3 storage plug-in mentioned above
  • When it comes to putting the htpasswd file online, I converted it into a single string with “n” characters for newlines so that it could be outputted to its own file by CircleCI.
  • For more information, check out packages/verdaccio in this private Bot Land repo.

It seems like setting max_users to -1 is only supposed to disable registration, but it also disables logging in. As a workaround, I just set max_users to 1 no matter how many current users there are; this disables registration (so long as you have one user already) but still allows people to log in.

Note that you can’t set it to 0 since that will allow infinite registrations thanks to this line of code.

Couldn’t publish package: request entity too large”

Section titled Couldn’t publish package: request entity too large”

This is just that max_body_size is set too low (it defaults to 10MB) (reference).