How to Health Check Docker Compose Container with cURL

Docker offers internal Health checks for your containers. What if you want to use cURL and your Docker container HealthCheck strategy? Let’s dive in and find out how.

Healthcheck is designed to check the current container. This means cURL must run within the container you want to test. In this short guide, you will learn how to get cURL ready and HealthCheck Docker Compose with cURL.

What is Docker Compose Health Checks?

Docker Compose run containers. You need to health check the status of your containerized services. The steps of a container Healthchecks are defined in the docker-compose.yml using a healthcheck key within a service.

This way, Docker will periodically assess the health of your container and make decisions based on the results.

How to Use HealthChecks in Docker Compose with cURL

Before attempting to HealthCheck a Docker Compose container with cURL, you will need a working docker-compose.yml file. I have the following basic example of working with a Nginx container:

version: '3.9'
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 1m
      timeout: 10s
      retries: 3

Based on this HealthCheck section, you must have:

• test with the cURL command to run for the health check. interval will set the time between consecutive health checks. timeout is the maximum time allowed for a single health check with your service. retries works if the HealthCheck fails. It adds the number of consecutive failures allowed before considering the service unhealthy.

How cURL works with Docker Compose HealthCheck

This service uses cURL to send a request to test if the service is running. cURL is used in the health check command as ["CMD", "curl", "-f", "http://localhost"]. This way, cURL will fetch the root URL http://localhost to test if the service is running.

The -f set cURL command to fail on error. But note that http://localhost is only applicable to this service. Each service test command changes based on the container itself. For example, you can have the ["CMD", "curl", "-f", "http://localhost:3015/readiness"] command on a service running on 3015 and exposing the /readiness endpoint. Here cURL must be updated as such.

Running the Container

Since you have the healthcheck ready, you will run your container and cURL will kick off to check if your service can be deemed healthy.

docker-compose up --build -d

Once that is ready and after starting your services, check the health status using the following command:

docker-compose ps

If your container was considered unhealthy, you would have the following error:

At some point, the service will need cURL installed within the container. Check this How to Install and Use cURL in Docker Containers guide for such cases.

Running cURL based on Docker Compose service name

As a tip, you need to note that using a URL such as http://localhost:3015/ or http://localhost may fail to work with cURL within Docker.

On Docker, your service name is your localhost id. This way you need to replace localhost with the container name as follows:

version: '3.9'
services:
  websrv:
    image: httpd:latest
    ports:
      - "80:80"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://websrv"]
      interval: 1m
      timeout: 10s
      retries: 3

In this example, you have the service name as websrv. This means the cURL health check command will use http://myapp as the target URL

Run your container and check its status using docker compose ps. This approach should work as follows:

Conclusion

Note: As a side note, always use the service name in the Docker compose to healthcheck the status and not localhost.

I hope you have learned how Health Check Docker Compose with cURL.