Private npm Registry

This add-on is operated by Nodejitsu

Private npm from Nodejitsu

Private npm Registry

Last Updated: 17 February 2015

Table of Contents

Private npm from Nodejitsu is a way of easily creating and installing packages from your own personal npm registry. This allows to you to create private packages while still falling back to the public registry for every other package.

Provisioning the add-on

Private npm can be attached to a Heroku application via the CLI:

$ heroku addons:add private-npm --app [your-app]

Plans (private-npm:[plan]) can be any one of: iron, steel, bronze, silver, gold, platinum, or diamond.

A list of all plans available can be found here.

We provide extra commandline arguments if you want to use them. If you want to pick the name of your subdomain, and use your regular public npm user, you can pass them in, otherwise, we will generate them for you.

Example:

$ heroku addons:add private-npm:iron --app [app] --subdomain=[subdomain] \
  --owner=[npm-username] --password=[npm-password]
  • --app: the app to be assoicated with this addon.
  • --subdomain: the desired subdomain for this npm registry.
  • --owner: your npm username.
  • --password: your npm password.

None of these arguments are mutually inclusive.

Getting started

In this getting started guide you will get set up with your Hosted Private NPM registry from Nodejitsu as well as learn about some of the best practices for working with package.json files.

But first, take a look at this 4 minute introduction to our Private npm solution.

Configure the npm CLI

Just like the public registry, the npm CLI program is what you’ll use to install, publish and otherwise interact with npm modules. Nodejitsu Private npm has three changes in the configuration to your npm CLI client:

$ npm config set always-auth true
$ npm config set strict-ssl true
$ npm config set ca ""

Why do you need to do these things?

  • Every request requires authentication: This means that users you have not authorized cannot download packages from your Private npm. Since this is not the default behavior of the public npm you need to set:
$ npm config set always-auth true
  • Be strict about SSL: We improved our SSL experience, now our Private npm registry supports multi-level wildcard certificate issued by DigiCert and serves https://*.registry.nodejitsu.com, so you’ll need to set the following to your npm config:
$ npm config set strict-ssl true
$ npm config set ca ""

Login & start making requests against your Private npm

Requests can be made against your Private npm in two ways:

  • Set the registry for all requests: This means that every request will hit your private registry
  $ npm config set registry https://your-subdomain.registry.nodejitsu.com
  • Use the --reg flag when necessary: The --reg flag (short for --registry) will allow you to make any request against your private registry:
  $ npm login
  $ npm info your-private-module --reg http://your-subdomain.registry.nodejitsu.com

We recommend that you set the registry for all requests to avoid any accidental publishes of private modules to the public registry. Since all new publishes go by default to your Private npm registry when you need to publish a new public npm package you can explicitly set the --reg flag:

  $ cd /my/new/public/package
  $ npm init
  $ npm publish --reg https://registry.npmjs.org

More information available at the Command Line Interface Documentation

Log in to the Web Interface

http://your-subdomain.npm.nodejitsu.com

More information available at the Web Interface Documentation

Tip: Publish modules using publishConfig

The publishConfig in your package.json does the following (from the npm documentation):

This is a set of config values that will be used at publish-time. It’s especially handy if you want to set the tag or registry, so that you can ensure that a given package is not tagged with “latest” or published to the global public registry by default.

Any config values can be overridden, but of course only “tag” and “registry” probably matter for the purposes of publishing.

For example:

{
  "publishConfig": {
    "registry": "https://your-subdomain.registry.nodejitsu.com"
  }
}

The benefits of using publishConfig is that it avoids accidental publishes to the public registry due to user error. Take for example a developer on your team who has not properly configured their machine by running npm config set registry or using the --reg flag. That command would send your code public. By using the publishConfig property you avoid that because it is part of your application.

Using with Heroku buildpacks

If you already have a Heroku app this is simple. If not, why don’t you checkout their getting started documentation. First (just like before) we recommend you create a specific deploy user for your private npm registry first. This allows you to separate access control from the personal accounts of the developers on your team.

npm config set https://<your-subdomain>.registry.nodejitsu.com
npm adduser
# Enter new credentials for your
# own deployment user.

Ensure you add this user to your private npm account at https://<your-subdomain>.npm.nodejitsu.com and you’re ready to go!

Now that we have your private npm deploy user created and added to your registry we just need to add a .npmrc file to the root directory of your application. Follow along below:

1. Backup your existing personal .npmrc file

cp ~/.npmrc ~/.npmrc-local

2. Login with your deploy user

npm login --registry https://registry.nodejitsu.com
# Enter the credentials for your deploy user

3. Copy your current .npmrc to your Heroku application

cp ~/.npmrc path/to/application
git add .
git commit -m 'Add private .npmrc'
git push heroku master

4. Restore your personal .npmrc file

mv ~/.npmrc-local ~/.npmrc

And … voila!

  • All of your private npm dependencies for your project you will be seamlessly installed for every deployment of your Heroku application.
  • You’ll always be able to deploy during public npm downtime since you’re now using our bifurcated and dedicated public replica: https://registy.nodejitsu.com

Web Interface

Visit our Web Interface documentation.

CLI

The following sections walk you through setup, package management and maintainers management.


Most of the workflow of npm is being done in the command line, we will show you the basic commands you’ll need to know to work with Private NPM from the CLI.

Private npm setup

First we need to set up our npm client to use your Private npm registry, with the following commands your local npm client will be ready to work with Private npm.

$ npm config set strict-ssl true
$ npm config set ca ""
$ npm config set registry https://<your-subdomain>.registry.nodejitsu.com

After setting this options you’ll need to login by running:

$ npm login

This will sync your Public npm user with our Private npm product.

Example:

$ npm config set strict-ssl true
$ npm config set ca ''
$ npm config set registry https://example.registry.nodejitsu.com
$ npm login
Username: (julianduque)
Email: (this is public) (julianduquej@gmail.com)
npm http PUT https://example.registry.nodejitsu.com/-/user/org.couchdb.user:julianduque
npm http 409 https://example.registry.nodejitsu.com/-/user/org.couchdb.user:julianduque
npm http GET https://example.registry.nodejitsu.com/-/user/org.couchdb.user:julianduque?write=true
npm http 200 https://example.registry.nodejitsu.com/-/user/org.couchdb.user:julianduque?write=true
npm http PUT https://example.registry.nodejitsu.com/-/user/org.couchdb.user:julianduque/-rev/18-e8bd0cf245e74215896b5ec1f4d797c5
npm http 201 https://example.registry.nodejitsu.com/-/user/org.couchdb.user:julianduque/-rev/18-e8bd0cf245e74215896b5ec1f4d797c5
$

Package Management

Next we will learn how to use npm for common package management.

Install Package

If you want to install a package from your private or public registry you’ll want to run:

$ npm install <package-name>

Example:

$ npm install private-module
npm http GET https://example.registry.nodejitsu.com/private-module
npm http 304 https://example.registry.nodejitsu.com/private-module
private-module@0.1.0 node_modules/private-module
$

Also if you want to save the package dependency in your package.json file just append the --save option to the command.

$ npm install <package-name> --save

Or if the package is a development dependency (like grunt, karma, etc.) you’ll want to append --save-dev instead.

$ npm install <package-name> --save-dev

Publish Package

Publish a package is so easy with npm, just run the following command to publish a package to your private registry (make sure you followed the setup steps properly).

$ npm publish

Example:

$ cd ~/private-module
$ npm publish
npm http PUT https://example.registry.nodejitsu.com/private-module
npm http 201 https://example.registry.nodejitsu.com/private-module
+ private-module@0.1.0
$

But if you want to publish the package to the public registry you can use the --reg option to define the npm registry to use.

$ npm publish --reg https://registry.npmjs.org

Unpublish Package

If you want to unpublish a package you’ll want to run:

$ npm unpublish <package-name> --force

Take into account that if you want to publish the package again you’ll need to use a different version in your package.json to avoid conflicts.

Maintainers Management

Work in a team is awesome right? With npm, team management is easy too!

List Maintainers

If you want to know the maintaners of a package run:

$ npm owner ls <package-name>

Example:

$ npm owner ls my-private-package
npm http GET https://example.registry.nodejitsu.com/my-private-package
npm http 304 https://example.registry.nodejitsu.com/my-private-package
julianduque <julianduquej@gmail.com>
indexzero <charlie.robbins@gmail.com>
jcrugzz <jcrugzz@gmail.com>
$

Add Maintainer

If you want to add a maintainer you’ll need to run:

$ npm owner add <username> <package-name>

Example:

$ npm owner add swaagie my-private-package
npm http GET https://example.registry.nodejitsu.com/-/user/org.couchdb.user:swaagie
npm http 304 https://example.registry.nodejitsu.com/-/user/org.couchdb.user:swaagie
npm http GET https://example.registry.nodejitsu.com/my-private-package
npm http 200 https://example.registry.nodejitsu.com/my-private-package
npm http PUT https://example.registry.nodejitsu.com/my-private-package/-rev/8-c33be2c90b28e0ae7c55
npm http 201 https://example.registry.nodejitsu.com/my-private-package/-rev/8-c33be2c90b28e0ae7c55
$ npm owner ls my-private-package
npm http GET https://example.registry.nodejitsu.com/my-private-package
npm http 200 https://example.registry.nodejitsu.com/my-private-package
julianduque <julianduquej@gmail.com>
indexzero <charlie.robbins@gmail.com>
jcrugzz <jcrugzz@gmail.com>
swaagie <info@martijnswaagman.nl>
$

Remove Maintainer

And if you want to remove a maintainer, run:

$ npm owner rm <username> <package-name>

After adding or removing a maintainer don’t forget to Sync it on the Web Interface using Sync Maintainers button.

FAQ

Will my private registry stay up If the public registry goes down?

Yes, it will remain online and you will be able to use npm without problems.

Can anyone else access my registry?

Only the team members defined in the Web Interface can access your registry.

How can I make sure I don’t accidentally publish to the public registry?

We recommend that you set the default to Private npm registry. This removes even the slightest chance that your private code could get published publicly accidentally.

$ npm config set https://{your-subdomain}.registry.nodejitsu.com

Alternatively, if you’re feeling bold: you can use the publishConfig property in your package.json:

For example:

{
  "publishConfig": {
    "registry": "https://your-subdomain.registry.nodejitsu.com"
  }
}

The publishConfig in your package.json does the following (from the npm documentation):

This is a set of config values that will be used at publish-time. It’s especially handy if you want to set the tag or registry, so that you can ensure that a given package is not tagged with “latest” or published to the global public registry by default.

Any config values can be overridden, but of course only “tag” and “registry” probably matter for the purposes of publishing.

What happens if I need to change my password on the public npm registry?

You will need to resync your new password with your Private npm registry. Youc an do this by:

$ npm config set registry https://your-subdomain.registry.nodejitsu.com
$ npm login