Keycloak docker compose with health checks

docker-compose.yml

# Keycloak containers doesn't come with curl or wget in it, this forces the users to use alternative mechanisms to realise 
# health check for the keycloak standard containers. This example leverages the capability of modern Java to dynamically 
# compile a *.java source file and execute it on the fly using the `java` command. The HealthCheck class uses
# java.net.URL to open a connection to the `health/live` endpoint of keycloak and exits the process with a non-zero status 
# if the http status is not `Ok`
version: '3'
services:
  ############################
  # Keycloak service
  ############################
  keycloak:
    image: quay.io/keycloak/keycloak:22.0.5
    command:
      - start-dev
      - --import-realm
    environment:      
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
      DB_VENDOR: h2
      KC_HEALTH_ENABLED: true
    ports:
      - '8080:8080'
    volumes:
      - ./keycloak:/opt/keycloak/data/import
    healthcheck:
      test: ['CMD-SHELL', '[ -f /tmp/HealthCheck.java ] || echo "public class HealthCheck { public static void main(String[] args) throws java.lang.Throwable { System.exit(java.net.HttpURLConnection.HTTP_OK == ((java.net.HttpURLConnection)new java.net.URL(args[0]).openConnection()).getResponseCode() ? 0 : 1); } }" > /tmp/HealthCheck.java && java /tmp/HealthCheck.java http://localhost:8080/health/live']
      interval: 5s
      timeout: 5s
      retries: 30

healthcheck:
test: ['CMD-SHELL', '[ -f /tmp/HealthCheck.java ] || echo "public class HealthCheck { public static void main(String[] args) throws java.lang.Throwable { System.exit(java.net.HttpURLConnection.HTTP_OK == ((java.net.HttpURLConnection)new java.net.URL(args[0]).openConnection()).getResponseCode() ? 0 : 1); } }" > /tmp/HealthCheck.java && java /tmp/HealthCheck.java http://localhost:9000/health/live']
interval: 5s
timeout: 5s
retries: 30

try to use your healthcheck like this

    healthcheck:
      test: ['CMD-SHELL', '[ -f /tmp/HealthCheck.java ] || echo "public class HealthCheck { public static void main(String[] args) throws java.lang.Throwable { System.exit(java.net.HttpURLConnection.HTTP_OK == ((java.net.HttpURLConnection)new java.net.URL(args[0]).openConnection()).getResponseCode() ? 0 : 1); } }" > /tmp/HealthCheck.java && java /tmp/HealthCheck.java http://localhost:9000/health/live']
      interval: 5s
      timeout: 5s
      retries: 30

For what it’s worth, I’ve updated my previous answer [1] to bump the Keycloak version to v26.1.0-0 (released on 2025-01-15), and I confirm that no changes to the health check logic were necessary.

[1] https://gist.github.com/sarath-soman/5d9aec06953bbd0990c648605d4dba07?permalink_comment_id=5376088#gistcomment-5376088

To avoid Java warning [deprecation] URL(String) in URL has been deprecated, I rewrote it like that:

    healthcheck:
      test: ['CMD-SHELL', '[ -f /tmp/HealthCheck.java ] || echo "public class HealthCheck { public static void main(String[] args) throws java.lang.Throwable { java.net.URI uri = java.net.URI.create(args[0]); System.exit(java.net.HttpURLConnection.HTTP_OK == ((java.net.HttpURLConnection)uri.toURL().openConnection()).getResponseCode() ? 0 : 1); } }" > /tmp/HealthCheck.java && java /tmp/HealthCheck.java http://localhost:9000/health/live']
      interval: 5s
      timeout: 5s
      retries: 5

Worked for me.

To avoid Java warning [deprecation] URL(String) in URL has been deprecated, I rewrote it like that:

    healthcheck:
      test: ['CMD-SHELL', '[ -f /tmp/HealthCheck.java ] || echo "public class HealthCheck { public static void main(String[] args) throws java.lang.Throwable { java.net.URI uri = java.net.URI.create(args[0]); System.exit(java.net.HttpURLConnection.HTTP_OK == ((java.net.HttpURLConnection)uri.toURL().openConnection()).getResponseCode() ? 0 : 1); } }" > /tmp/HealthCheck.java && java /tmp/HealthCheck.java http://localhost:9000/health/live']
      interval: 5s
      timeout: 5s
      retries: 5

Worked for me.

Worked for me too

To avoid Java warning [deprecation] URL(String) in URL has been deprecated, I rewrote it like that:

    healthcheck:
      test: ['CMD-SHELL', '[ -f /tmp/HealthCheck.java ] || echo "public class HealthCheck { public static void main(String[] args) throws java.lang.Throwable { java.net.URI uri = java.net.URI.create(args[0]); System.exit(java.net.HttpURLConnection.HTTP_OK == ((java.net.HttpURLConnection)uri.toURL().openConnection()).getResponseCode() ? 0 : 1); } }" > /tmp/HealthCheck.java && java /tmp/HealthCheck.java http://localhost:9000/health/live']
      interval: 5s
      timeout: 5s
      retries: 5

Worked for me.

Worse for me too. But I found a brief introduction at https://www.keycloak.org/observability/health and shared it with you, hoping it can help others in need.

    healthcheck:
      test: [
        "CMD-SHELL",
        "exec 3<>/dev/tcp/localhost/${ENV_KC_HTTP_MANAGEMENT_PORT:?}; \
        echo -en 'GET /health/ready' >&3; \
        # Give the server a moment to respond, then search for 'UP'
        if timeout 3 cat <&3 | grep -m 1 'UP'; then \
          exec 3<&-; exec 3>&-; exit 0; \
        else \
          exec 3<&-; exec 3>&-; exit 1; \
        fi"
      ]

Thanks @codespearhead! This worked for me using Keycloak 26.3.4.

Hi folks! You can now see the official docs for a little more concise healthcheck command.
It's a variant on the bash tcp socket redirect I independently figured out and described in a PR that got eventually merged 🙏.