README.adoc

sdavids-docker-healthcheck-js-nodejs

Table of Contents

• 1. Development
  • 1.1. Test
  • 1.2. Run
  • 1.3. Format Source Code
  • 1.4. Lint Source Code
• 2. Usage
• 3. Examples
  • 3.1. HTTP
  • 3.2. HTTPS

A Node.js-based Docker health check for an HTTP(S) URL passed in via ENV.

ℹ️	The health check URL has to return HTTP 200. The response body is not evaluated.

ℹ️	HTTP, HTTP with HTTPS redirect, and HTTPS URLs are supported. For security reasons only 3 redirects is followed. Modify the healthcheck to increase the number of redirects: src/healthcheck.mjs const maxRedirects = 3;

Tip	You can use http://captive.apple.com and https://captive.apple.com for testing.

This health check uses the HTTP(S) URL passed in via the following ENV variable:

HEALTHCHECK_URL

the HTTP URL to be used for the health check

If HEALTHCHECK_URL is not set http://localhost:3000/-/health/liveness will be used.

❗	The health check calls the URL from within the container therefore localhost is the running Docker image and not the localhost of the Docker host.

1. Development

$ npm install --no-ignore-scripts

1.1. Test

$ scripts/test.sh

1.2. Run

$ node src/healthcheck.mjs
$ echo $?
0

$ HEALTHCHECK_URL=http://captive.apple.com node src/healthcheck.mjs
$ echo $?
0

$ NODE_EXTRA_CA_CERTS=ca.crt HEALTHCHECK_URL=https://localhost:3000/-/health/liveness node src/healthcheck.mjs
$ echo $?
0

0

the health check URL returned HTTP 200

64

the health check URL was invalid

69

the maximum number of redirects has been exceeded

70

the health check had an internal software error

76

the service at the given healthcheck URL uses a self-signed certificate or a certificate with an invalid certificate chain

78

the Node.js runtime does not support HTTPS

100

the health check URL did not return HTTP 200

1.3. Format Source Code

$ scripts/format.sh

1.4. Lint Source Code

$ scripts/lint.sh

2. Usage

1. Copy the health check into your container:

   Dockerfile

   COPY src/healthcheck.mjs /node/

2. Configure the health check:

   Dockerfile

   HEALTHCHECK --interval=5s --timeout=5s --start-period=5s \
       CMD node --no-warnings /node/healthcheck.mjs

   More information:

   Dockerfile reference - HEALTHCHECK

3. (Optional) Pass the HEALTHCHECK_URL to the docker container run invocation:

   scripts/docker_start.sh

   docker container run \
   ...
     --env HEALTHCHECK_URL='https://localhost:3000/-/health/liveness' \
   ...

   Alternatively, add the HEALTHCHECK_URL to the Dockerfile:

   Dockerfile

   ENV HEALTHCHECK_URL="https://localhost:3000/-/health/liveness"

4. (Optional) If you have an https healthcheck URL with a custom certificate authority you need to mount the certificate authorities root certificate and set the environment variable NODE_EXTRA_CA_CERTS to make it available to the Node.js runtime:

   docker container run \
     --volume "$PWD/ca.crt:/node/ca.crt:ro" \
     --env NODE_EXTRA_CA_CERTS='/node/ca.crt' \
     ...

   Alternatively, you could add it to your image:

   COPY ca.crt /node/
   
   ENV NODE_EXTRA_CA_CERTS=/node/ca.crt

3. Examples

3.1. HTTP

Dockerfile: a simple HTTP server

1. Build the image:

   $ scripts/docker_build.sh

2. Start a container:

   $ scripts/docker_start_http.sh
   
   Listen local: http://localhost:3000
   
   The URL has been copied to the clipboard.

   ⇒ http://localhost:3000

3. Examine the two endpoints:

   $ curl -s -o /dev/null -w "%{http_code}" http://localhost:3000
   200
   $ curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/-/health/liveness
   200

4. Get the health status:

   $ scripts/docker_health.sh
   healthy 0

5. Stop the container:

   $ scripts/docker_stop.sh

6. Remove all Docker artifacts related to this project:

   $ scripts/docker_cleanup.sh

3.2. HTTPS

Dockerfile: a simple HTTPS server

1. CA root certificate

   1. Create a new certificate authority and copy its root certificate:

      $ scripts/create_ca.sh
      $ scripts/copy_ca_root_cert.sh

   2. Copy the existing certificate authorities root certificate:

      $ scripts/copy_ca_root_cert.sh

1. localhost certificate

   1. Create a new localhost certificate:

      $ scripts/create_ca_based_cert.sh

   2. Copy the existing localhost certificate:

      $ scripts/copy_ca_based_cert.sh

2. Build the image:

   $ scripts/docker_build.sh

3. Start a container:

   $ scripts/docker_start_https.sh
   
   Listen local: https://localhost:3000
   
   The URL has been copied to the clipboard.

   ⇒ https://localhost:3000

   ℹ️	If you see Listen local: http://localhost:3000 instead: Either cert.pem or key.pem could not be read; try creating the localhost certificate again.

4. Examine the two endpoints:

   $ curl -s -o /dev/null -w "%{http_code}" https://localhost:3000
   200
   $ curl -s -o /dev/null -w "%{http_code}" https://localhost:3000/-/health/liveness
   200

5. Get the health status:

   $ scripts/docker_health.sh
   healthy 0

6. Stop the container:

   $ scripts/docker_stop.sh

7. Remove all Docker artifacts related to this project:

   $ scripts/docker_cleanup.sh

8. (Optional) Delete the certificate authority.

   Tip	You usually want to keep the certificate authority so you can use for other projects.