Skip to main content

HEALTHCHECK Configuration and Troubleshooting in Docker Container for Nexus Lifecycle

Updated

.

Problem 

HEALTHCHECK is a Docker feature that determines a container's state. In Nexus Lifecycle (IQ Server), the default health check runs on the admin port (8071). If the container does not pass the health check, it is marked as unhealthy, which can lead to monitoring, automation, or container orchestration issues.

HEALTHCHECK in the Nexus Lifecycle image

Use version 1.175.0 as an example,  and go to its IMAGE LAYERS

Click line 48 and check the health check command:

HEALTHCHECK &{["CMD-SHELL" "curl --fail --silent --show-error http://localhost:8071/healthcheck || exit 1"] "0s" "0s" "0s" '\x00'}

http://localhost:8071/healthcheck returns a JSON containing each feature's health status(example):

{
  "database": {
    "healthy": true,
    "duration": 0,
    "insight_brain_ods database": "roundTripTimeInMs=0",
    "insight_brain_dm database": "roundTripTimeInMs=0",
    "insight_brain_aggregation database": "roundTripTimeInMs=0",
    "insight_brain_third_party_scans database": "roundTripTimeInMs=0",
    "timestamp": "2024-04-26T18:06:58.545Z"
  },
  "deadlocks": {
    "healthy": true,
    "duration": 0,
    "timestamp": "2024-04-26T18:06:58.549Z"
  },
  "newDatabaseConnections": {
    "healthy": true,
    "duration": 3,
    "insight_brain_ods database": "roundTripTimeInMs=0",
    "insight_brain_dm database": "roundTripTimeInMs=0",
    "insight_brain_aggregation database": "roundTripTimeInMs=0",
    "insight_brain_third_party_scans database": "roundTripTimeInMs=0",
    "timestamp": "2024-04-26T18:06:58.549Z"
  },
  "product-license": {
    "healthy": true,
    "duration": 0,
    "remainingDays": 0,
    "timestamp": "2024-04-26T18:06:58.549Z"
  },
  "work-directory": {
    "healthy": true,
    "duration": 0,
    "timestamp": "2024-04-26T18:06:58.545Z"
  }
}

The IQ container is healthy only if all the features' are healthy(healthy is true).

Symptoms 

The IQ container is marked as unhealthy when running docker ps.

Screenshot 2024-04-26 at 2.28.50 PM.png

Note: a license is required. Otherwise, it's unhealthy.

Possible causes

  1. Missing or Expired License: The IQ Server requires a valid license to pass the health check.

  2. Incorrect Admin Port Configuration: The health check URL must be updated if the IQ server runs on a non-default port (not 8071).

  3. Modifications to the Health Check Command: Custom Docker configurations may override the default health check behavior.

Solution 

Step 1: Verify the Current Health Check

Run the following command to check the container’s health status:

docker inspect <container-name>

Look for the Healthcheck section:

"Healthcheck": {
  "Test": [
    "CMD-SHELL",
    "curl --fail --silent --show-error http://localhost:8071/healthcheck || exit 1"
  ]
}

If the IQ server runs on a non-default port, this URL must be changed.

Step 2: Updating HEALTHCHECK for Non-Default Ports

2.1 Start a Container with a Custom Docker Command

If IQ Server runs on a different admin port (e.g., 18071), modify the docker run command by:

--health-cmd='curl --fail --silent --show-error http://localhost:18071/healthcheck || exit 1'

Example:

docker run -d -p 18070:18070 -p 18071:18071 --name nexus-iq-server-2 \
    -v /home/ec2-user/docker-pv/config/config.yml:/etc/nexus-iq-server/config.yml \
    --health-cmd='curl --fail --silent --show-error http://localhost:18071/healthcheck || exit 1' \
     sonatype/nexus-iq-server

Note: Ensure the port number matches the configuration in config.yml.

2.2 Updating HEALTHCHECK in Docker Compose

For deployments using Docker Compose, add the health check under the service configuration:

version: "1"
services:
  iqcl:
    image: sonatype/nexus-iq-server:1.175.0
    volumes:
      - /home/ec2-user/docker-pv/sonatype-work:/sonatype-work
      - /home/ec2-user/docker-pv/config:/etc/nexus-iq-server
    restart: always
    ports:
      - "18070:18070"
      - "18071:18071"
    healthcheck:
      test: curl --fail --silent --show-error http://localhost:18071/healthcheck || exit 1

Related articles