DEV Community

Cover image for Docker healthcheck experiments with Go web app

Posted on • Originally published at

Docker healthcheck experiments with Go web app

One good way to monitor your container status is to use Docker's HEALTHCHECK feature.

As part of testing the followed actions upon an unhealthy container, I had to experiment how this works. I wrote a small Go app that replies to /health requests, and the status it responds is configurable.

The webserver listens on $PORT (defaults to 8080). To change its status, simply make an api call to one of the supported actions. You can either connect the container to execute it,
or if you have mapped a port on the host, you can use it.

Supported actions are:

  • /sabotage will make it respond with 500.
  • /timeout will make it respond after 20s.
  • /recover will return it back to healthy state, with 200 response code.

You can find the source code here.

From the Docker docs -

The HEALTHCHECK instruction has two forms:

    HEALTHCHECK [OPTIONS] CMD command (check container health by running a command inside the container)
    HEALTHCHECK NONE (disable any healthcheck inherited from the base image)

The HEALTHCHECK instruction tells Docker how to test a container to check that it is still working. 
This can detect cases such as a web server that is stuck in an infinite loop and unable 
to handle new connections, even though the server process is still running.

When a container has a healthcheck specified, it has a health status in addition to its normal status. 
This status is initially starting. Whenever a health check passes, it becomes healthy (whatever state 
it was previously in). After a certain number of consecutive failures, it becomes unhealthy.
Enter fullscreen mode Exit fullscreen mode

The options that can appear before CMD are:

--interval=DURATION (default: 30s)
--timeout=DURATION (default: 30s)
--start-period=DURATION (default: 0s)
--retries=N (default: 3)
Enter fullscreen mode Exit fullscreen mode

You can configure the HEALTHCHECK settings in the Dockerfile or the docker-compose.yml. In my example,
I use it in the Dockerfile.


  1. Clone the repo and build the image: docker build . -t go-healthchecker

  2. Bring up the container, wait until it gets healthy.

Run the container

  1. To change the healthcheck response, connect to the container and update its status


In a future blog post, I will share how you can use the HEALTHCHECK feature to control docker-compose services startup with a more fine-grained option, e.g "How to make service X start before service Y".

Top comments (0)