Create lean Node.js image with Docker multi-stage build

4 min read

Alexei Ledenev · Apr 24, 2017

TL;DR

Starting from Docker 17.05+, you can create a single Dockerfile that can build multiple helper images with compilers, tools, and tests and use files from above images to produce the final Docker image. Read this simple tutorial and create a free Codefresh account to build, test and deploy images instantly.

The “core principle” of Dockerfile

Docker can build images by reading the instructions from a Dockerfile. A Dockerfile is a text file that contains a list of all the commands needed to build a new Docker image. The syntax of Dockerfile is pretty simple and the Docker team tries to keep it intact between Docker engine releases.

The core principle is very simple: 1 Dockerfile -> 1 Docker Image.

This principle works just fine for basic use cases, where you just need to demonstrate Docker capabilities or put some “static” content into a Docker image.

Once you advance with Docker and would like to create secure and lean Docker images, a single Dockerfile is not enough.

People who insist on following the above principle find themselves with slow Docker builds, huge Docker images (several GB size images), slow deployment time and lots of CVE violations embedded into these images.

The Docker Build Container pattern

Docker Pattern: The Build Container

The basic idea behind Build Container pattern is simple:

Create additional Docker images with required tools (compilers, linters, testing tools) and use these images to produce lean, secure and production ready Docker image.

An example of the Build Container pattern for typical Node.js application:

Derive FROM a Node base image (for example node:6.10-alpine) node and npm installed (Dockerfile.build)
Add package.json
Install all node modules from dependency and devDependency
Copy application code
Run compilers, code coverage, linters, code analysis and testing tools
Create the production Docker image; derive FROM same or other Node base image
install node modules required for runtime (npm install --only=production)
expose PORT and define a default CMD (command to run your application)
Push the production image to some Docker registry

This flow assumes that you are using two or more Dockerfiles and a shell script or flow tool to orchestrate all steps above.

Example

I use a fork of Let’s Chat node.js application. Here is the link to our fork.

Builder Docker image with eslint, mocha and gulp

FROM alpine:3.5

# install node 
RUN apk add --no-cache nodejs
# set working directory
WORKDIR /root/chat
# copy project file
COPY package.json .
# install node packages
RUN npm set progress=false && \
    npm config set depth 0 && \
    npm install
# copy app files
COPY . .
# run linter, setup and tests
CMD npm run lint && npm run setup && npm run test

FROM alpine:3.5

# install node

RUN apk add --no-cache nodejs

# set working directory

WORKDIR /root/chat

# copy project file

COPY package.json .

# install node packages

RUN npm set progress=false && \

npm config set depth 0 && \

npm install

# copy app files

COPY . .

# run linter, setup and tests

CMD npm run lint && npm run setup && npm run test

Production Docker image with ‘production’ node modules only

FROM alpine:3.5

# install node
RUN apk add –no-cache nodejs tini
# set working directory
WORKDIR /root/chat
# copy project file
COPY package.json .
# install node packages
RUN npm set progress=false && \
    npm config set depth 0 && \
    npm install --only=production && \
    npm cache clean
# copy app files
COPY . .
# Set tini as entrypoint
ENTRYPOINT [“/sbin/tini”, “--”]
# application server port
EXPOSE 5000
# default run command
CMD npm run start

FROM alpine:3.5

# install node

RUN apk add –no-cache nodejs tini

# set working directory

WORKDIR /root/chat

# copy project file

COPY package.json .

# install node packages

RUN npm set progress=false && \

npm config set depth 0 && \

npm install --only=production && \

npm cache clean

# copy app files

COPY . .

# Set tini as entrypoint

ENTRYPOINT [“/sbin/tini”, “--”]

# application server port

EXPOSE 5000

# default run command

CMD npm run start

What is Docker multi-stage build?

Docker 17.05 extends Dockerfile syntax to support new multi-stage build, by extending two commands: FROM and COPY.

The multi-stage build allows using multiple FROM commands in the same Dockerfile. The last FROM command produces the final Docker image, all other images are intermediate images (no final Docker image is produced, but all layers are cached).

The FROM syntax also supports AS keyword. Use AS keyword to give the current image a logical name and reference to it later by this name.

To copy files from intermediate images use COPY --from=<image_AS_name|image_number>, where number starts from 0 (but better to use logical name through AS keyword).

Creating a multi-stage Dockerfile for Node.js application

The Dockerfile below makes the Build Container pattern obsolete, allowing to achieve the same result with the single file.

#
# ---- Base Node ----
FROM alpine:3.5 AS base
# install node
RUN apk add --no-cache nodejs-current tini
# set working directory
WORKDIR /root/chat
# Set tini as entrypoint
ENTRYPOINT ["/sbin/tini", "--"]
# copy project file
COPY package.json .

#
# ---- Dependencies ----
FROM base AS dependencies
# install node packages
RUN npm set progress=false && npm config set depth 0
RUN npm install --only=production 
# copy production node_modules aside
RUN cp -R node_modules prod_node_modules
# install ALL node_modules, including 'devDependencies'
RUN npm install

#
# ---- Test ----
# run linters, setup and tests
FROM dependencies AS test
COPY . .
RUN  npm run lint && npm run setup && npm run test

#
# ---- Release ----
FROM base AS release
# copy production node_modules
COPY --from=dependencies /root/chat/prod_node_modules ./node_modules
# copy app sources
COPY . .
# expose port and define CMD
EXPOSE 5000
CMD npm run start

# ---- Base Node ----

FROM alpine:3.5 AS base

# install node

RUN apk add --no-cache nodejs-current tini

# set working directory

WORKDIR /root/chat

# Set tini as entrypoint

ENTRYPOINT ["/sbin/tini", "--"]

# copy project file

COPY package.json .

# ---- Dependencies ----

FROM base AS dependencies

# install node packages

RUN npm set progress=false && npm config set depth 0

RUN npm install --only=production

# copy production node_modules aside

RUN cp -R node_modules prod_node_modules

# install ALL node_modules, including 'devDependencies'

RUN npm install

# ---- Test ----

# run linters, setup and tests

FROM dependencies AS test

COPY . .

RUN npm run lint && npm run setup && npm run test

# ---- Release ----

FROM base AS release

# copy production node_modules

COPY --from=dependencies /root/chat/prod_node_modules ./node_modules

# copy app sources

COPY . .

# expose port and define CMD

EXPOSE 5000

CMD npm run start

The above Dockerfile creates 3 intermediate Docker images and single release Docker image (the final FROM).

First image FROM alpine:3.5 AS bas – is a base Node image with: node, npm, tini (init app) and package.json
Second image FROM base AS dependencies – contains all node modules from dependencies and devDependencies with additional copy of dependencies required for final image only
Third image FROM dependencies AS test – runs linters, setup and tests (with mocha); if this run command fail not final image is produced
The final image FROM base AS release – is a base Node image with application code and all node modules from dependencies

Try Docker multi-stage build today

In order to try Docker multi-stage build, you need to get Docker 17.05, which is going to be released in May and currently available on the beta channel.

So, you have two options:

Use beta channel to get Docker 17.05
Run dind container (docker-in-docker)

Running Docker-in-Docker 17.05 (beta)

Running Docker 17.05 (beta) in docker container (--privileged is required):

$ docker run -d --rm --privileged -p 23751:2375 --name dind \
    docker:17.05.0-ce-dind --storage-driver overlay2

1 2	$ docker run -d --rm --privileged -p 23751:2375 --name dind \ docker:17.05.0-ce-dind --storage-driver overlay2

Try mult-stage build. Add --host=:23751 to every Docker command, or set DOCKER_HOST environment variable.

$ # using --host
$ docker --host=:23751 build -t local/chat:multi-stage .

$ # OR: setting DOCKER_HOST
$ export DOCKER_HOST=localhost:23751
$ docker build -t local/chat:multi-stage .

$ # using --host

$ docker --host=:23751 build -t local/chat:multi-stage .

$ # OR: setting DOCKER_HOST

$ export DOCKER_HOST=localhost:23751

$ docker build -t local/chat:multi-stage .

Summary

With Docker multi-stage build feature, it’s possible to implement an advanced Docker image build pipeline using a single Dockerfile .

Kudos to Docker team for such a useful feature!

Hope, you find this post useful. I look forward to your comments and any questions you have.

PS Codefresh just added multi-stage build support, Please go on and create a free Codefresh account to try this out.

New to Codefresh? Schedule a FREE onboarding and start making pipelines fast. and start building, testing and deploying Docker images faster than ever.

23 responses to “Create lean Node.js image with Docker multi-stage build”

Simon Wydooghe says:

April 30, 2017 at 12:01 pm

Cheers, good explanation and clean Dockerfile!

Reply
kiwenlau says:

May 1, 2017 at 2:23 am

Thx for the blog. However, the build process failed…

npm ERR! Linux 3.13.0-91-generic
npm ERR! argv “/usr/bin/node” “/usr/bin/npm” “run” “lint”
npm ERR! node v6.9.2
npm ERR! npm v3.10.9

npm ERR! missing script: lint
npm ERR!
npm ERR! If you need help, you may report this error at:
npm ERR!

npm ERR! Please include the following file with any support request:
npm ERR! /root/chat/npm-debug.log

Reply
Kris Meister says:

May 1, 2017 at 4:39 pm

I was thinking there was a way to build only one stage. But it looks like Docker will go through all stages, only the last stage in the Dockerfile is the what will be assigned as the image?

This doesn’t help if I want i want to end on an earlier stage. Such as if I have a dev stage, is there anyway to start the container in that stage?

Reply
1. Alexei Ledenev says:
  
  May 24, 2017 at 2:24 pm
  
  You can always create a new Docker container from any LAYER. Just run docker history command to see all image layers. Then select some layer, for example b3616e272dc1 and run it as a container:
  
  $ docker run -it --rm b3616e272dc1 sh
  
  if you like to keep specific layer for future use, tag it:
  
  $ docker tag b3616e272dc1 myrepo/myimage:master
  
  Reply
Pascal Andy says:

May 3, 2017 at 10:44 pm

This is great! NowI would like to mix this with pkg (https://github.com/zeit/pkg)

I think that would be the ultimate NodeApp deployment setup 🙂

Reply
Shane lee says:

May 4, 2017 at 11:57 am

Interesting article. Would I be correct in saying this mirrors a CI build pipeline?

Reply
Jay O'Conor says:

May 17, 2017 at 8:27 pm

Correction: The docker version required for this is 17.05+, not 17.0.5+. That erroneous extra decimal point makes a difference

Reply
1. Dan Garfield says:
  
  May 17, 2017 at 9:29 pm
  
  Thanks Jay, fixed!
  
  Reply
Alexander Zigelski says:

June 16, 2017 at 8:46 am

What is the difference between executing npm install in an intermediate container, then copy it in the final one vs. Just executing npm install in the final container?

Reply
1. Alexei Ledenev says:
  
  June 16, 2017 at 8:09 pm
  
  Speed.
  Why downloading npm packages twice? For a small project it makes no difference, but for real project, it can take minutes (depends on network latency).
  
  Reply
Finnian Anderson says:

July 2, 2017 at 12:08 am

I’d love to see an extended example of this with a compose file – any chance?
Thanks!

Reply
Francisco Berrocal says:

September 1, 2017 at 4:37 pm

This will work only if you configure your lint, setup and test as production dependencies, right?

Reply
1. Alexei Ledenev says:
  
  September 2, 2017 at 7:23 am
  
  The basic idea is to have 2 folders in base image: one with production dependencies and other with dev.
  Then test intermediate image could use (copy) dev dependencies from base and release image will copy only production dependencies.
  If test intermediate image fails some test or lint rule, final release image won’t be built.
  
  Reply
Hire NodeJS Developer says:

November 4, 2017 at 3:30 pm

Fantastic Post! Thank you so much for sharing this kind of wonderful post..!!

Reply
Jonathan says:

November 22, 2017 at 3:04 am

Cool feature!

If the dockerfile step for say linting fails, would it stop it from progressing to the next chain?

Reply
1. Alexei Ledenev says:
  
  November 22, 2017 at 9:58 am
  
  Any failed command (one that exits with non-zero code) will stop the Docker build
  
  Reply
Jonathan says:

November 22, 2017 at 3:09 am

Btw:

RUN npm install –only=production

copy production node_modules aside

RUN cp -R node_modules prod_node_modules

That’s smart!

Reply
spurtcommerce says:

December 6, 2017 at 10:38 am

Your article is very nice… thanks for shairng your information….

Reply
ariden says:

December 18, 2017 at 9:06 am

Hello,

Is it possible to launch only a specific stage in the docker-compose file ?

I want to run unit tests separately when I want to,

for example:

i want to report tests in jenkinsfile in a specific file, as report.xml and I want to launch

junit report.xml

thx

Reply
1. Enrico Stahn says:
  
  May 29, 2018 at 1:54 am
  
  A couple of observations:
  
  I haven’t seen any solution that isn’t running sequentially. We run NPM Lint, NPM tests, image build, … all in parallel to maximise speed.
  Caching of NPM modules across multiple CI runs – How is this working?
  
  Reply
  1. Alexei Ledenev says:
    
    May 29, 2018 at 10:17 am
    
    For caching between CI builds, we (in Codefresh) are using high-iops network volumes mounted into builder container, so subsequent builds, even if running on different machines will reuse the same volume (ot it’s clone, depending on load and git branching).
    
    Reply
Brian K says:

March 13, 2019 at 8:36 pm

Very helpful write-up. Thanks Alexei. I went from only knowing a few basics of a regular dockerfile to having one that reduced my image size from 224MB to 127MB by simply using your pattern of copying folders from a “dependencies” stage. My dockerfile is also easier to follow now.

One side note: you might consider adding a something about using the –target arg with docker build. In my dockerfile I added a stage for creating the image for use locally (vs in a deployed env). If I want the prod version, I simply use: “docker build -t name:tag .” If I want the local version I use: “docker build –target local -t name:tag .” Here’s the dockerfile for reference:

BEGIN

FROM node:lts-alpine as base
WORKDIR /home/node/app

FROM base as dependencies
COPY . .
RUN npm install -g typescript &&\
npm install –only=production &&\
cp -R node_modules prod_node_modules &&\
npm run build

FROM base as release
COPY –from=dependencies –chown=node:node /home/node/app/prod_node_modules node_modules
COPY –from=dependencies –chown=node:node /home/node/app/dist dist
COPY –from=dependencies –chown=node:node /home/node/app/config config
USER node:node
EXPOSE 4000
ENV NODE_ENV production
ENTRYPOINT [“node”, “dist/index.js”]

FROM release as local
COPY –from=dependencies –chown=node:node /home/node/app/some-config-file-that-kubernetes-makes-available-through-a-mount /config/needed-config-file

FROM release

END

Reply
Mihir says:

July 16, 2019 at 9:37 am

This article is very useful for me because I am a Node.js developer. Do you have any post regarding how to install and configure docker?

Reply