Skip to content



Repository files navigation


This project is a fork of local-npm, which at the time I write this is unmaintained/discontinued. modserv hasn't hit a 1.0 release yet, but I use it daily as my primary registry mirror and in a company setting where it has served me faithfully and with much better reliability than ever did.

Run as a docker container (prefered method)

docker run --detach --restart=always -p 80:80 --name my-registry --volume registry:/srv/data_volume wmhilton/modserv

The config file and the downloaded registry data are stored in a persistant volume (which we named registry) mounted inside the container at /srv/data_volume. Where Docker creates volumes is system specific, but you can find the host mountpoint with:

root@ubuntu:~$ docker volume inspect registry
        "Driver": "local",
        "Labels": null,
        "Mountpoint": "/var/lib/docker/volumes/registry/_data",
        "Name": "registry",
        "Options": {},
        "Scope": "local"

Now that you know the config file is /var/lib/docker/volumes/registry/_data/config.json you can edit it to set the url-base, ui-url, etc to suit your needs. Whenever you edit it, restart the docker container with docker restart my-registry.

Install as a service (un-maintained)

git clone
npm link

Note: the install script has only been tested on Ubuntu and could use a lot of work


modserv is a Node server that acts as a local npm registry. It serves modules, caches them, and updates them whenever they change. Basically it's a local mirror, but without having to replicate the entire npm registry.

This allows your npm install commands to (mostly) work offline. Also, they get faster and faster over time, as commonly-installed modules are aggressively cached.


modserv acts as a proxy between you and the main npm registry. You run npm install commands like normal, but under the hood, all requests are sent through the local server.

When you first npm install a module, it'll be fetched from the main npm registry. After that, the module and all its dependencies (at that version) are stored in a local database, so you can expect subsequent installs to be much faster.

The server will also listen for changes from the remote registry, so you can expect updates to a module's metadata to be replicated within seconds of being published. (I.e. you won't get stuck with old versions.)

If you're organizing a conference/meetup/whatever, you can also share this local server with multiple people. So if your teammates are constantly installing the same modules over and over again, this can save a lot of time in the long run.

modserv is also a good way to make npm install work offline. Assuming new versions of a package haven't been published since you last installed, subsequent npm installs will all serve from the cache, without ever hitting a remote server.

Command line options

For the command modserv:

-h, --help        : show help
-p, --port        : port (default: 5080)
-P, --pouch-port  : pouchdb-server port (default: 16984)
-l, --log         : pouchdb-server log level (error|warn|info|debug)
-r, --remote      : remote fullfatdb (default:
-R, --remote-skim : remote skimdb (default:
-u, --url-base    : base url you want clients to use for fetching tarballs,
                      e.g. if you are using tunneling/proxying
-v, --version     : show version number
-d, --directory   : directory to store data (default: "./")

Protip: You can replicate from your friend's modserv to your own modserv by simply pointing at it:

$ modserv \
   --remote http://<friends_hostname>:5080 \
   --remote-skim http://<friends_hostname>:16984/skimdb

While your friend does:

$ modserv \
   --url-base http://<friends_hostname>:5080

In this way, you can create a daisy chain of awesome.

Protip 2: If you want to set up a single modserv for multiple people to use, such as for conferences or workplaces, then just daemonize it (e.g. using forever), and then when you run it, specify the URL that clients will use to access the server, e.g.:

$ modserv \
    --url-base http://192.168.x.x:5080

This will ensure that clients fetch tarballs from 192.168.x.x instead of

Browser UI

A rudimentary npm-like UI that allows you to search modules and see their descriptions can be found at http://localhost:5080/_browse.

If you haven't finished replicating the remote skimdb, then not all the modules will be visible yet.


A next generation registry (WIP)







No packages published


  • JavaScript 72.3%
  • CSS 25.4%
  • HTML 1.6%
  • Other 0.7%