Private NPM Registry Replicator Document

For my future reference and to help others trying to set up a private NPM registry which sits behind a [corporate] proxy and requires authenticated CouchDB admin access, here’s the replicator document that I ended up using:

   "_id": "registry",
   "source": "",
   "target": "registry",
   "user_ctx": {
       "name": "myadmin_username",
       "roles": ["_admin"]
   "continuous": true,
   "owner": "myadmin_username",
   "proxy": "http://proxy:8080"

For those who are not familiar with CouchDB, the above is a document that needs to be created in _replicator database, so that the replication rule from public NPM registry to your private NPM registry can be persisted and runs continuously.

The key here is the user_ctx, owner, continuous, and proxy settings, which after several trials and errors, I managed to get them right with several clean full replication runs (always monitor CouchDB log during replication!).

Have a look at CouchDB Replication wiki page and this gist on the new replicator database (introduced in CouchDB v1.2.0) for explanation on those fields and how CouchDB replication works.


If you tried to be smart by copying the design documents from the public NPM registry to your private NPM registry before replicating the documents, you would see some errors in CouchDB log file due to some rules in the latest design document that would fail the older documents. For example: module name must be in lower case, but there are old modules with name containing upper case letter(s).

My suggestion is to start from empty registry and public_users databases, then kick off the replication, and refresh the indices nearing the end of the replication, followed by compacting the databases and views to save some disk space.

Tip 2:

Public NPM registry sets require_valid_user = false in its CouchDB configuration file, which allows database read access without CouchDB admin authentication. If you set require_valid_user = true instead, then CouchDB will require authentication when you fetch any module (a document from CouchDB’s point of view). Unfortunately, as of NPM v1.2.15, there’s no authentication info on its fetch request, so you might find this monkey patch and this issue handy.

Tip 3:

And if you want to make the private NPM registry available over SSL:

  1. Generate self-signed SSL certificate

  2. Enable SSL on CouchDB via local.ini configurations

  3. Configure registry URL in .npmrc file to use https://

  4. npm install

If you get DEPTH_ZERO_SELF_SIGNED_CERT error, you might want to check this issue for workarounds. If you’re connecting via a proxy, you might get ‘tunneling socket could not be established, cause=Parse Error’ error.

Tip 4:

If you are working behind an older proxy server, there’s a chance that your replication might fail because the proxy rejects lengthy GET request URL. To get around this problem, you need to patch MAX_URL_LEN with a larger value. /hattip: Adam Kocoloski

Tip 5:

If you are seeing this error:

[error] [<0.18564.6>] Uncaught server error: {insecure_rewrite_rule, <<“too many ../.. segments”>>}

You need to set this in CouchDB configuration .ini file:

[httpd] secure_rewrites=false

Share Comments
comments powered by Disqus