How to Set Up a Private npm Registry with cnpmjs on Ubuntu

npm is an essential package manager for front‑end development, but many organizations need a private registry to host internal or customized packages that cannot be published to the public npm registry.

This tutorial shows how to create a private npm registry using the cnpmjs framework on an Ubuntu 18.04 server, including MySQL installation, cnpmjs deployment, configuration, and package publishing.

1. Install MySQL

sudo apt-get install mysql-server
sudo apt-get install mysql-client
sudo apt-get install libmysqlclient-dev

After installation, set the root password and enable remote connections:

use mysql;
update user set authentication_string=PASSWORD("your_password") where User='root';
update user set plugin="mysql_native_password";
flush privileges;
exit

mysql -u root -p

# Allow remote connections
GRANT ALL PRIVILEGES ON *.* TO 'myuser'@'%' IDENTIFIED BY 'mypassword' WITH GRANT OPTION;
FLUSH PRIVILEGES;
sudo vim /etc/mysql/mysql.conf.d/mysqld.cnf   # comment out bind-address = 127.0.0.1
service mysql restart

2. Deploy cnpmjs

git clone https://github.com/cnpm/cnpmjs.org.git
cd npmjs.org
# Use a stable 2.x version
git checkout 2.19.4
npm i

Edit config/index.js to set ports, database, and other options. Example snippets:

registryPort: 7001, // npm registry port
webPort: 7002, // web UI port
//bindingHost: '127.0.0.1', // comment out for external access

database: {
  db: 'cnpmjs',
  username: 'root',
  password: '',
  dialect: 'mysql',
  host: '127.0.0.1',
  port: 3306,
}

// Private mode (only admins can publish)
enablePrivate: false,
scopes: ['@jacob']
admins: { admin: '[email protected]' }

3. Create database tables

mysql -u root -p
create database cnpmjs;
source docs/db.sql;

After running the script, the required tables appear in the MySQL database.

4. Start the service

npm i pm2 -g
pm2 start ./dispatch.js

Check the status with pm2 status . Open ports 7001 and 7002 in the server’s security group, then access the registry UI at http://your-host:7002 .

5. Publish a package to the private registry

npm config set registry http://lcs.show:7001
npm adduser
npm login

Modify package.json name to include the configured scope (e.g., @jacob/aeditor ) and run:

npm publish

Verify the package appears in the UI and install it with:

npm i @jacob/aeditor

6. Advanced configuration

cnpmjs can synchronize packages from the public npm registry. Two sync modes are available:

Manual sync – click SYNC on a missing package page.

Automatic sync – set syncModel in config/index.js to none , exist , or all .

When syncing all packages, storage can grow quickly. To offload packages to cloud storage, install qn-cnpm and configure the NFS driver:

npm i qn-cnpm

nfs: require('qn-cnpm')({
  accessKey: 'your access key',
  secretKey: 'your secret key',
  bucket: 'qiniu',
  domain: 'http://qiniu-sdk-test.qiniudn.com'
});

7. Common issues

400 Bad Request – invalid scope: ensure the package scope is listed in scopes in the config.

403 Forbidden – no_perms: the logged‑in npm user is not an admin and the package lacks a proper scope.

8. References

cnpmjs official deployment guide: https://github.com/cnpm/cnpmjs.org/wiki/Deploy

Step‑by‑step article on building an enterprise npm private registry: https://juejin.im/post/6844904196651630599

CNPM private npm service tutorial: http://blog.fens.me/nodejs-cnpm-npm/