README.adoc

sdavids-docker-healthcheck-go-http

Table of Contents

• 1. Development
  • 1.1. Build
  • 1.2. Test
  • 1.3. Run
  • 1.4. Format Source Code
  • 1.5. Lint Source Code
  • 1.6. Release Build
• 2. Usage
• 3. Example

A Go-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.

💡	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(S) URL to be used for the health check

If HEALTHCHECK_URL is not set https://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.

❗	There is no check whether the given HEALTHCHECK_URL is a syntactically correct HTTP(S) URL.

1. Development

1.1. Build

$ scripts/build.sh

⇒ target/healthcheck

1.2. Test

$ scripts/test.sh

1.3. Run

$ target/healthcheck
$ echo $?
0

$ HEALTHCHECK_URL=http://captive.apple.com target/healthcheck
$ echo $?
0

$ HEALTHCHECK_URL=https://captive.apple.com target/healthcheck
$ echo $?
0

0

the health check URL returned HTTP 200

69

the health check URL was unreachable

100

the health check URL did not return HTTP 200

1.4. Format Source Code

$ scripts/format.sh

1.5. Lint Source Code

$ scripts/lint.sh

1.6. Release Build

$ scripts/build_release.sh

⇒ target/healthcheck

2. Usage

1. Copy the health check into your container:

   Dockerfile

   COPY --from=healthcheck \
     /app/target/healthcheck \
     /usr/local/bin/healthcheck

2. Configure the health check:

   Dockerfile

   HEALTHCHECK --interval=5s --timeout=5s --start-period=5s \
       CMD healthcheck || exit 1

   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 add the certificate authorities root certificate to your image; for example for Alpine-based images:

   COPY ca.crt /usr/local/share/ca-certificates/
   
   # hadolint ignore=DL3018
   RUN apk add --no-cache ca-certificates && \
       update-ca-certificates

3. Example

Dockerfile: a simple HTTPS server

1. Create a new localhost certificate:

   $ scripts/create_self_signed_cert.sh

2. Build the image:

   $ scripts/docker_build.sh

3. Start a container:

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

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. Delete the localhost certificate:

   $ scripts/delete_self_signed_cert.sh