Using Docker with Private NPM Packages: Setup and Authentication

In the previous tutorial we showed you the steps required to download a private package to CI/deployment server. The tutorial you are about to read will give you an understanding of how to use Docker containers for private packages. if you haven't read our last two tutorial we recommend that you check them out, as this tutorial is part three of our working with private packages series.

Docker and private packages

In our tutorial on working with private packages, you must have observed that for you to use private packages, you have to be logged in to npm via the npm CLI.

When using environments such as a CI server or a Docker container, you will not be able to log in directly to npm, you will have to get and export an npm token as an environment variable. The token that you generate should look like this:

NPM_TOKEN=00000000-0000-0000-0000-000000000000

If you don't know how to generate a token, read our tutorial on Downloading packages to CI/deployment servers. If the workflow contained in Downloading packages to CI/deployment servers is what you need then that is perfect. However, if it doesn't suit your need, in this tutorial we will look at the problems associated with that workflow when running npm install in a Docker container.

Runtime variables

Consider the case where you have the following Dockerfile:

FROM risingstack/alpine:3.3-v4.2.6-1.1.3

COPY package.json package.json
RUN npm install

# Add your source files
COPY . .
CMD ["npm","start"]

Which uses the Alpine Node.js Docker image by RisingStack, to copy the package.json into your container, install all dependencies, copy the source files, and run the start command as specified in the package.json.

If you want to install private packages, the initial attempt will be to run npm install, with the use of the ENV parameter:

ENV NPM_TOKEN=00000000-0000-0000-0000-000000000000

However, this approach will not work as expected, this is because you want the npm install to occur when you run the docker build command, but in this instance, the ENV variables are set for runtimes only, hence they are not used during docker build.

Build-time variables

Since Docker 1.9, there is a different way of passing environment variables to Docker. We have to use ARG parameter.

A complete example that allows us use -build-arg to pass in our NPM_TOKEN requires that we add a .npmrc file to our project. The .npmrc file should contain the following content:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

The Dockerfile that will take advantage of this has a few more lines in it than our examples earlier that enables us to use the .npmrc file and the ARG parameter.

FROM risingstack/alpine:3.3-v4.2.6-1.1.3

ARG NPM_TOKEN  
COPY .npmrc .npmrc
COPY package.json package.json
RUN npm install

# Add your source files
COPY . .
CMD ["npm","start"]

This will add the expected ARG NPM_TOKEN, but it will also copy the .npmrc file and remove it once the npm install completes.

If you want to build the image using this Dockerfile and the token, run the following (note the . that is at the end to give docker build the current directory as an argument):

docker build --build-arg NPM_TOKEN=${NPM_TOKEN} .

The command above will build the Docker image with your current NPM_TOKEN environment variable, now you can run npm install inside your container as the current logged in user!

It should be noted that even when you delete the .npmrc file, it will still be in the commit history. To clean your secret up, you have to ensure that you squash the .npmrc file.

Previous: Downloading packages to CI or deployment servers.
Next: NPM Coding Style Guide: Best Practices and Conventions.