Docker Compose Elasticsearch service and Java API Client 8.x startup readiness interoperability

Answer to the main question

The signal that guarantees the cluster is ready for API calls in a Compose‑based dev environment is the /\_cluster/health endpoint returning a green (or, if acceptable, yellow) status. In Compose you expose this via a healthcheck on the elasticsearch service and then use depends_on: { condition: service_healthy } for the Java service. This ensures the Java client only starts after the cluster has allocated all primary shards and is reachable through the REST API.

Why the default depends_on is insufficient

• depends_on waits for the container to start listening on the port, but not for shard allocation or cluster formation.
• Without a health check the Java client can send requests that hit unassigned shards, resulting in 503/504 errors during tests or first‑time startup.

Coordinating version pinning

Keep the Docker image tag and the Java client dependency in sync by defining a single version property or BOM. For example, if you use elasticsearch:8.14.3 in docker‑compose.yml, pin the Maven/Gradle dependency to 8.14.3:

// Maven example
<properties>
  <elasticsearch.version>8.14.3</elasticsearch.version>
</properties>
<dependency>
  <groupId>co.elastic.clients</groupId>
  <artifactId>elasticsearch-java</artifactId>
  <version>${elasticsearch.version}</version>
</dependency>

Both the Compose file and the build file should reference the same property to avoid drift.

Integration pattern to avoid race conditions

1. Compose healthcheck:

   services:
     elasticsearch:
       image: elasticsearch:8.14.3
       healthcheck:
         test: ["CMD-SHELL", "curl -s -f http://localhost:9200/_cluster/health?wait_for_status=green || exit 1"]
         interval: 10s
         timeout: 5s
         retries: 5
   

2. Java service depends_on:

   services:
     app:
       depends_on:
         elasticsearch:
           condition: service_healthy
   

3. Optional client‑side retry – if you want an extra safety net, wrap the first client request in a loop that retries until a 200 response is received from /\_cluster/health.

Practical verification steps

1. Run docker compose up -d.
2. Check Compose logs for "Health: healthy" on the Elasticsearch container.
3. From the Java container, execute curl http://elasticsearch:9200/_cluster/health and verify the status field is "green".
4. Run a simple client call (e.g., client.ping()) and confirm it succeeds before the application proceeds.

What you might still need to confirm

Do you require the cluster to be fully green before the application starts, or is yellow acceptable for your test scenarios? Knowing that will dictate whether the health‑check query should wait for green or yellow.