How to use docker multi-stage build to create optimal images for dev and production

Docker has sharply risen in popularity in the past years. It has been one of the tools that have changed the way we work as software engineers and DevOps Engineers. From Docker v 17.05 multi-stage build was introduced which helped abandon the older builder pattern with use of stages and target. This post discussed how you can exploit docker multi-stage build to build optimal images suited for dev/test and production with a NodeJs example application.


  • You are aware of docker and know the basic docker commands like build, exec
  • You know about docker-compose (not a necessity)

Docker multi-stage builds intro

Docker multi-stage build lets us build docker images in stages with multiple FROM statements. Files can be copied from one stage to another. A very good example would be how a 294 Mb Golang 1.13 official image (123 Mb even with Alpine) can be just as big as the go executable of your application. As Golang is compiled and gives out an executable binary, the first stage can be compiling it and the second stage can be an alpine image (5 Mb) just to run that executable. So, if your go app binary is 10 Mb your image can be 15 Mb (10 Mb binary + 5 Mb alpine) rather than the heavy 294 Mb official go image or 123 Mb alpine go image. You can have a look at an example too.

Another great example can be a frontend javascript application, you could use an app with node, webpack and all needed npm dev dependencies to build the application. In the next stage, it can be served with a minimal nginx apline image which will be of much less size.

Below is the official information about docker multi-stage builds:

With multi-stage builds, you use multiple FROM statements in your Dockerfile. Each FROM instruction can use a different base, and each of them begins a new stage of the build. You can selectively copy artifacts from one stage to another, leaving behind everything you don’t want in the final image.

Unfortunately, all the language don’t compile to an executable binary as golang does, still, you can leverage multi-stage builds to craft docker images that serve the purpose better. We look into how to do this below with an open-source node js application example.

Issues before multistage build

We are going to see an example Node Js app which is a currency converter API built with Express. Currently, the problems with the Dockerfile and build are as follows:

  1. Nodemon is installed on production
  2. Current docker image does not have dev dependencies (runs npm install --production)
  3. The image size can be made smaller (even though its using alpine)

Following are the current Dockerfile and docker-compose.yml for local development:


As we can see nodemon is installed even on production which is unnecessary on production. Another issue is there are no dev dependencies so tests can't be run inside docker.

CMD ["node", "index.js"]</span>

Docker Compose file

Don’t be concerned about the VIRTUAL_HOST and VIRTUAL_PORT that is for nginx proxy.

  build: .
   - .:/src
  command: npm start
    - "8080:8080"
    NODE_ENV: dev
    VIRTUAL_HOST: 'currency.test'
    VIRTUAL_PORT: 8080</span>

Current image size

Let’s look at how big is this image we got from running docker build . -t currency-api-original.

<noscript><img class="ds t u gq ak" src="*SRPN3Dlp5ZjQjmSZ.." width="2030" height="74" role="presentation"/></noscript>

So currently it is 165 Mb, hopefully, we can decrease its size too in this process.

Solution with multi-stage build

Now as we want to have dev dependencies and nodemon on dev builds and only production npm dependencies on production build, the docker related files have been modified as follows:

Dockerfile with multi-stage build

COPY package.json package-lock.json /src/
COPY . /src
EXPOSE 8080</span><span id="4a65" class="jk id ef at hw b fa jo jp jq jr js jm r jn">FROM base as production</span><span id="6abb" class="jk id ef at hw b fa jo jp jq jr js jm r jn">ENV NODE_ENV=production
RUN npm install --production</span><span id="0458" class="jk id ef at hw b fa jo jp jq jr js jm r jn">CMD ["node", "index.js"]</span><span id="25fa" class="jk id ef at hw b fa jo jp jq jr js jm r jn">FROM base as dev</span><span id="4787" class="jk id ef at hw b fa jo jp jq jr js jm r jn">ENV NODE_ENV=development
RUN npm config set unsafe-perm true && npm install -g nodemon
RUN npm install
CMD ["npm", "start"]</span>

Let’s analyze what changed here and why? Following are the highlights:

  • We start with a base image that has node, then copy needed files to the image like 1–5
  • For production, we set the NODE_ENV to production and install non-dev dependencies, also notice that we run node (not nodemon)
  • Later the last 6 lines of the Dockefile, we create the image from the base and set NODE_ENV to development, then we install nodemon as we want to watch the files on dev
  • On dev image build we install all npm dependencies including dev ones so that we can run tests

The builds are more streamlined and we have optimized our docker images to be more environment-specific. We solved the above-mentioned issues and don’t have nodemon and dev dependencies on production and we can run our tests on dev/test. That's a win!

Docker-compose file after multi-stage build

The main change for the docker-compose file is the target:dev in the build parameters.

version: '3.5'
      context: ./
      target: dev
    - .:/src
    command: npm start
      - "8080:8080"
      NODE_ENV: dev
      VIRTUAL_HOST: 'currency.test'
      VIRTUAL_PORT: 8080</span>

All the changes made can be viewed in this pull request too. Let’s look at how big is the image now:

<noscript><img class="ds t u gq ak" src="*TzH3B3R7APs-VP5L.." width="2030" height="148" role="presentation"/></noscript>

We ran the following commands to build the dev and the production images:

  • docker build . -t currency-api-dev -target=dev
  • docker build . -t currency-api-dev -target=production

We have shaved off ~25 Mb from the older image for a production build. It happened because we removed nodemon and some dev dependencies for production. Even for the dev build it is ~21 Mb smaller.

Conclusion / tl;dr

The main point here is to build docker images apt for the environment and multi-stage builds are an answer to this problem. You can use the same concept to build images for PHP with composer. For example, the dev build can have xdebug for debugging and production build can have opcache enabled by default.

Anytime you need different things for different environments, opt for docker multi-stage builds and avoid having 3 different dockerfiles.

No Comments Yet