README.adoc

Node Docker Image Slimming

Table of Contents

• 1. Techniques
  • 1.1. Results
  • 1.2. Running the Example
  • 1.3. Example REST API
  • 1.4. More Information
• 2. License
  • 2.1. Contribution
• 3. Code of Conduct
• 4. Development Environment Setup
  • 4.1. Installation
    • 4.1.1. Docker
    • 4.1.2. Node Version Manager
    • 4.1.3. shellcheck
    • 4.1.4. yamllint
    • 4.1.5. hadolint
  • 4.2. API Tools
    • 4.2.1. OpenAPI
    • 4.2.2. Postman
    • 4.2.3. RapidAPI
    • 4.2.4. JetBrains IDEs
    • 4.2.5. Visual Studio Code
    • 4.2.6. cURL
• 5. Build Tasks
  • 5.1. Development
    • 5.1.1. start
    • 5.1.2. start:dev
  • 5.2. Building
    • 5.2.1. build
    • 5.2.2. start:build
    • 5.2.3. clean
  • 5.3. Code Quality
    • 5.3.1. format
    • 5.3.2. format:checks
    • 5.3.3. lint
    • 5.3.4. lint:fix
  • 5.4. Docker
    • 5.4.1. docker:build
    • 5.4.2. docker:cleanup
    • 5.4.3. docker-health
    • 5.4.4. docker-logs
    • 5.4.5. docker:sh
    • 5.4.6. docker:start
    • 5.4.7. docker:start:secure
    • 5.4.8. docker:stop
  • 5.5. Misc
    • 5.5.1. clean:node
    • 5.5.2. cert:create
    • 5.5.3. cert:delete

This repository showcases several techniques for creating smaller Node.js Docker images:

1. .dockerignore file

2. multi-stage build

3. smaller base image

4. image hardening

5. UPX

6. cleaning up node_modules

7. JavaScript bundling

The example is an Express-based REST API packaged in a Docker image with a HEALTHCHECK.

TLDR

1950.0 MB ⇒ 93.4 MB (-95.21%)

1. Techniques

The final result with all techniques applied can be found in the main branch:

• Dockerfile

• scripts/docker-build.sh

The other branches showcase a single technique—​the last commit of the branch contains the changes for the specific technique.

⚠️	All branches besides main will be force-pushed to in order to keep them up-to date with the main branch and remain a single commit.

1.1. Results

#	Branch	Layer Count	Image Size (MB)	node_modules Size (MB)	server.mjs Size (B)
0	000-base	33	1950.0	140.0	2139
1	001-dockerignore	35	1770.0	120.0	2139
2	002-alpine	31	382.0	119.7	2139
3	003-alpine-npm-ci	31	233.0	38.3	2139
4	004-alpine-clean-modules	31	217.0	22.4	2139
5	005-alpine-multi-stage-build	29	216.0	22.4	2139
6	006-alpine-alpine-final	24	116.0	22.4	2139
7	007-alpine-upx	26	114.0	22.4	2139
8	008-alpine-hardening	30	114.0	22.4	2139
9	009-alpine-webpack	30	114.0	22.4	1189
9	009-alpine-esbuild-external	30	114.0	22.4	1136
9	009-alpine-esbuild	29	93.4	0	4750597

0. baseline with the default variant of the offical NodeJS Docker image for building the image and serving the example REST API with no optimizations

1. use a .dockerignore file and specific COPY commands

   ℹ️	The ls_extensions and ls_extensions_git functions might help fine-tuning your .dockerignore file.

2. use the alpine variant of the offical NodeJS Docker image for both building and running

3. use npm ci --omit dev --omit optional --omit peer instead of npm i

   ℹ️	Depending on your project setup you might not be able to omit the peer dependencies.

4. use the clean-modules npm package to clean up the node_modules directory

   ℹ️	clean-modules will have more impact once there are more dependencies.

5. use a multi-stage build

6. use the official Alpine Docker image for serving the example REST API

   ℹ️	Depending on your project setup you might have to install more packages via apk add --no-cache. The dependencies of docker run --rm alpine apk add nodejs might be a starting point.

7. use UPX to compress the node binary

8. harden the final alpine image

   ℹ️	Hardening does not only decrease the image size but also makes it significantly more secure.

9. bundle the example REST API

   ℹ️	Bundling will have more impact once there are more source files to bundle.

   1. use webpack

   2. use esbuild; esbuild --bundle --minify --packages=external

      ℹ️	Minified JavaScript makes debugging production issues harder.

   3. use esbuild; esbuild --bundle --minify

      ℹ️	Minified JavaScript makes debugging production issues harder.

1.2. Running the Example

1. Build the Docker image:

   $ npm run docker:build

2. Start the image (HTTP server):

   $ npm run docker:start

   ⇒ http://localhost:3000

3. Stop the image:

   $ npm run docker:stop

4. Create a self-signed certificate:

   $ npm run cert:create

5. Start the image (HTTPS server):

   $ npm run docker:start:secure

   ⇒ https://localhost:3000

There are also other build tasks available.

1.3. Example REST API

The example exposes two endpoints (OpenAPI 3 Description):

/

returns a randomly generated user in JSON format

/-/health/liveness

liveness probe

You can use several API Tools to interact with the API.

1.4. More Information

• .dockerignore file

• Dockerfile - COPY

• node:<version>-alpine

• npm-ci

• npm-ci --omit

• npm-cache

• clean-modules

• Multi-stage builds

• Official Alpine Docker Image

• UPX

• iron-alpine

• webpack

• esbuild - Bundling for node

2. License

Apache License, Version 2.0 (LICENSE or www.apache.org/licenses/LICENSE-2.0).

2.1. Contribution

See CONTRIBUTING.adoc.

3. Code of Conduct

We abide by the Contributor Covenant, Version 2.1 and ask that you do as well.

For more information, please see CODE_OF_CONDUCT.adoc.

4. Development Environment Setup

4.1. Installation

4.1.1. Docker

Install Docker.

4.1.2. Node Version Manager

Install fnm or NVM.

ℹ️	This repository uses husky for Git hooks. More information: Husky - Command not found

fnm

~/.zprofile

if command -v fnm > /dev/null 2>&1; then
  eval "$(fnm env --use-on-cd)"
fi

~/.config/husky/init.sh

#!/usr/bin/env sh

# vim:ft=zsh

# shellcheck shell=sh disable=SC1091

set -eu

[ -e /etc/zshenv ] && . /etc/zshenv
[ -e "${ZDOTDIR:=${HOME}}/.zshenv" ] && . "${ZDOTDIR:=${HOME}}/.zshenv"
[ -e /etc/zprofile ] && . /etc/zprofile
[ -e "${ZDOTDIR:=${HOME}}/.zprofile" ] && . "${ZDOTDIR:=${HOME}}/.zprofile"
[ -e /etc/zlogin ] && . /etc/zlogin
[ -e "${ZDOTDIR:=${HOME}}/.zlogin" ] && . "${ZDOTDIR:=${HOME}}/.zlogin"

nvm

~/.zshrc

export NVM_DIR="${HOME}/.nvm"

[ -s "${NVM_DIR}/nvm.sh" ] && . "${NVM_DIR}/nvm.sh"
[ -s "${NVM_DIR}/bash_completion" ] && . "${NVM_DIR}/bash_completion"

if command -v nvm > /dev/null 2>&1; then
  autoload -U add-zsh-hook
  load-nvmrc() {
    local nvmrc_path="$(nvm_find_nvmrc)"
    if [ -n "${nvmrc_path}" ]; then
      local nvmrc_node_version=$(nvm version "$(cat "${nvmrc_path}")")
      if [ "${nvmrc_node_version}" = "N/A" ]; then
        nvm install
      elif [ "${nvmrc_node_version}" != "$(nvm version)" ]; then
        nvm use
      fi
    elif [ -n "$(PWD=$OLDPWD nvm_find_nvmrc)" ] && [ "$(nvm version)" != "$(nvm version default)" ]; then
      echo "Reverting to nvm default version"
      nvm use default
    fi
  }

  add-zsh-hook chpwd load-nvmrc
  load-nvmrc
fi

~/.config/husky/init.sh

#!/usr/bin/env sh

# vim:ft=zsh

# shellcheck shell=sh disable=SC1091

set -eu

[ -e /etc/zshenv ] && . /etc/zshenv
[ -e "${ZDOTDIR:=${HOME}}/.zshenv" ] && . "${ZDOTDIR:=${HOME}}/.zshenv"
[ -e /etc/zprofile ] && . /etc/zprofile
[ -e "${ZDOTDIR:=${HOME}}/.zprofile" ] && . "${ZDOTDIR:=${HOME}}/.zprofile"
[ -e /etc/zlogin ] && . /etc/zlogin
[ -e "${ZDOTDIR:=${HOME}}/.zlogin" ] && . "${ZDOTDIR:=${HOME}}/.zlogin"

export NVM_DIR="${HOME}/.nvm"

if [ -f "${NVM_DIR}/nvm.sh" ]; then
  . "${NVM_DIR}/nvm.sh"

  if [ -f ".nvmrc" ]; then
    nvm use
  fi
fi

4.1.3. shellcheck

Linux

$ sudo apt-get install shellcheck

Mac

$ brew install shellcheck

4.1.4. yamllint

Linux

$ sudo apt-get install yamllint

Mac

$ brew install yamllint

4.1.5. hadolint

Linux

Install hadolint.

Mac

$ brew install hadolint

4.2. API Tools

4.2.1. OpenAPI

Open:

OpenAPI 3 Description

4.2.2. Postman

Install Postman.

Import:

• Postman Collection

• Postman 'local' Environment

• Postman 'local secure' Environment

More Information

• Troubleshooting Self-signed SSL Certificate Issues and More in Postman

4.2.3. RapidAPI

Install RapidAPI.

Open:

• RapidAPI Project

4.2.4. JetBrains IDEs

Install and enable the HTTP Client plugin.

Open:

• HTTP requests file

use with the local or local-secure environments defined in:

• HTTP environment file

More Information

• Execute HTTP requests

• Disable certificate verification

4.2.5. Visual Studio Code

Install and enable the REST Client extension.

Add the following snippet to .vscode/settings.json:

    "rest-client.environmentVariables": {
        "local": {
            "host": "http://localhost",
            "port": "3000"
          },
          "local-secure": {
            "host": "https://localhost",
            "port": "3000"
          }
    }

Open:

• HTTP requests file

Switch (Ctrl+Alt+E / macOS: ⌘ Сmd+⌥ Opt+E) to the local or local-secure environment.

More Information

• REST Client - Environments

4.2.6. cURL

$ curl http://localhost:3000/
$ curl http://localhost:3000/-/health/liveness

$ curl --insecure https://localhost:3000/
$ curl --insecure https://localhost:3000/-/health/liveness

More Information

• REST Client - Environments

5. Build Tasks

5.1. Development

5.1.1. start

Runs the app from the source files (src/js/).

$ npm start

⇒ localhost:3000

5.1.2. start:dev

Runs the app from the source files (src/js/); restarting on file changes.

$ npm run start:dev

⇒ localhost:3000

5.2. Building

5.2.1. build

Builds the app.

$ npm run build

⇒ dist/

5.2.2. start:build

Runs the app generated by build (dist/).

$ npm run start:build

⇒ localhost:3000

5.2.3. clean

Deletes dist/ generated by build.

$ npm run clean

5.3. Code Quality

5.3.1. format

Format files with prettier.

$ npm run format

5.3.2. format:checks

Checks the formatting of the files with prettier.

$ npm run format:check

5.3.3. lint

Find problems via ESLint.

$ npm run lint

5.3.4. lint:fix

Fix problems via ESLint.

$ npm run lint:fix

5.4. Docker

5.4.1. docker:build

Builds the app’s image.

$ npm run docker:build

5.4.2. docker:cleanup

Removes all containers, volumes, and images previously created by this project.

$ npm run docker:cleanup

5.4.3. docker-health

Displays the health status of the app’s container.

$ npm run docker:health

5.4.4. docker-logs

Displays the logs of the app’s container.

$ npm run docker:logs

5.4.5. docker:sh

Opens a shell into the running app’s container.

$ npm run docker:sh

5.4.6. docker:start

Starts the app in a container exposing an HTTP port.

$ npm run docker:start

⇒ http://localhost:3000

5.4.7. docker:start:secure

Starts the app in a container exposing an HTTPS port.

$ npm run docker:start:secure

⇒ https://localhost:3000

❗	One needs to create the necessary private key and certificate via cert:create.

5.4.8. docker:stop

Stops the app’s container.

$ npm run docker:stop

5.5. Misc

5.5.1. clean:node

Deletes node_modules/ and package-lock.json.

$ npm run clean:node

5.5.2. cert:create

Creates a private key and a self-signed certificate.

$ npm run cert:create

⇒ docker/certs/cert.pem and docker/certs/key.pem

ℹ️	The generated certificate is valid for 30 days.

MacOS

Check your login keychain in Keychain Access; Secure Sockets Layer (SSL) should be set to "Always Trust":

ℹ️	Chrome and Safari need no further configuration.

Firefox (MOZILLA_PKIX_ERROR_SELF_SIGNED_CERT)

You need to bypass the self-signed certificate warning by clicking on "Advanced" and then "Accept the Risk and Continue":

Related Scripts

1. cert_delete

5.5.3. cert:delete

Deletes the private key and the self-signed certificate.

Usage

$ npm run cert:delete

Firefox

You can delete the certificate via Firefox > Preferences > Privacy & Security > Certificates; click "View Certificates…​":

Click on the "Servers" tab:

Related Scripts

1. cert_create