Dev Services for Elasticsearch

If any Elasticsearch-related extension is present (e.g. quarkus-elasticsearch-rest-client or quarkus-hibernate-search-orm-elasticsearch), Dev Services for Elasticsearch automatically starts an Elasticsearch server in dev mode and when running tests. So, you don’t have to start a server manually. The application is configured automatically.

Enabling / Disabling Dev Services for Elasticsearch

Dev Services for Elasticsearch is automatically enabled unless:

  • quarkus.devservices.enabled is set to false.

  • quarkus.elasticsearch.devservices.enabled is set to false

  • the hosts property is configured, depending on the extension used it can be:

  • quarkus.elasticsearch.hosts

  • quarkus.hibernate-search-orm.elasticsearch.hosts

Dev Services for Elasticsearch relies on Docker to start the server. If your environment does not support Docker, you will need to start the server manually, or connect to an already running server.

Shared Elasticsearch

Sometimes you need to share the server between applications. Dev Services for Elasticsearch implements a service discovery mechanism for your multiple Quarkus applications running in dev mode to share a single server.

Dev Services for Elasticsearch starts the container with the quarkus-dev-service-elasticsearch label which is used to identify the container.

If you need multiple (shared) servers, you can configure the quarkus.elasticsearch.devservices.service-name attribute and indicate the server name. It looks for a container with the same value, or starts a new one if none can be found. The default service name is elasticsearch.

Sharing is enabled by default in dev mode, but disabled in test mode. You can disable the sharing with quarkus.elasticsearch.devservices.shared=false.

Setting the port

By default, Dev Services for Elasticsearch picks a random port and configures the application. You can set the port by configuring the quarkus.elasticsearch.devservices.port property.

Note that the Elasticsearch hosts property is automatically configured with the chosen port.

Configuring the image

Dev Services for Elasticsearch support distributions based on both Elasticsearch and OpenSearch images.

When using Hibernate Search, Dev Services will default to Elasticsearch or OpenSearch based on Hibernate Search configuration.

Otherwise, Dev Services will default to Elasticsearch. To use OpenSearch, configure the distribution explicitly:

quarkus.elasticsearch.devservices.distribution=opensearch

If you need to use a different Elasticsearch or OpenSearch image than the default one you can configure it via:

quarkus.elasticsearch.devservices.image-name=docker.io/elastic/elasticsearch:8.9.1

For exotic image names, Quarkus might be unable to infer the distribution (elastic or opensearch). In these cases starting the Dev Services will fail, and you will need to configure the distribution explicitly:

quarkus.elasticsearch.devservices.image-name=my-custom-image-with-no-clue-about-the-distribution:1.0
quarkus.elasticsearch.devservices.distribution=elasticsearch

Reusing Dev Services

General case

Within a dev mode session or test suite execution, Quarkus will always reuse Elasticsearch Dev Services as long as their configuration (username, password, environment, port bindings, …​) did not change.

When the configuration of Elasticsearch Dev Services changes, Quarkus will always restart the corresponding containers.

When a dev mode session or test suite execution ends, Quarkus will (by default) stop Elasticsearch Dev Services.

Reusing Dev Service containers across runs

If you want to keep Dev Service containers running after a dev mode session or test suite execution to reuse them in the next dev mode session or test suite execution, this is possible as well. Just enable TestContainers reuse by inserting this line in one of your TestContainers configuration file (generally ~/.testcontainers.properties or C:/Users/myuser/.testcontainers.properties):

testcontainers.reuse.enable=true

Even with container reuse enabled, containers will only be reused if their startup command did not change: same environment variables (username/password in particular), same port bindings, …​

Reusing containers implies reusing their internal state, including the Elasticsearch schema and the content of indexes.

If that’s not what you want — and if your tests write to the indexes, that’s probably not what you want — consider reinitializing your schema and data on application startup. If you use Hibernate Search, Hibernate Search’s schema management may help with that.

With container reuse enabled, old containers (especially with obsolete configuration) might be left running indefinitely, even after starting a new Quarkus dev mode session or test suite execution.

In that case, you will need to stop and remove these containers manually.

If you want to reuse containers for some Quarkus applications but not all of them, or some Dev Services but not all of them, you can disable this feature for a specific Dev Service by setting the configuration property quarkus.elasticsearch.devservices.reuse to false.

Current limitations

Currently, only the default backend for Hibernate Search Elasticsearch is supported, because Dev Services for Elasticsearch can only start one Elasticsearch container.

Configuration reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

Whether this Dev Service should start with the application in dev mode or tests.

Dev Services are enabled by default unless connection configuration (e.g. quarkus.elasticsearch.hosts) is set explicitly.

Environment variable: QUARKUS_ELASTICSEARCH_DEVSERVICES_ENABLED

Show more

boolean

Optional fixed port the dev service will listen to.

If not defined, the port will be chosen randomly.

Environment variable: QUARKUS_ELASTICSEARCH_DEVSERVICES_PORT

Show more

int

The Elasticsearch distribution to use.

Defaults to a distribution inferred from the explicitly configured image-name (if any), or by default to the distribution configured in depending extensions (e.g. Hibernate Search), or by default to elastic.

Environment variable: QUARKUS_ELASTICSEARCH_DEVSERVICES_DISTRIBUTION

Show more

elastic, opensearch

The Elasticsearch container image to use.

Defaults depend on the configured distribution:

  • For the elastic distribution: docker.io/elastic/elasticsearch:8.9.1

  • For the opensearch distribution: docker.io/opensearchproject/opensearch:2.9.0

Environment variable: QUARKUS_ELASTICSEARCH_DEVSERVICES_IMAGE_NAME

Show more

string

The value for the ES_JAVA_OPTS env variable.

Environment variable: QUARKUS_ELASTICSEARCH_DEVSERVICES_JAVA_OPTS

Show more

string

-Xms512m -Xmx1g

Whether the Elasticsearch server managed by Quarkus Dev Services is shared.

When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Elasticsearch starts a new container.

The discovery uses the quarkus-dev-service-elasticsearch label. The value is configured using the service-name property.

Container sharing is only used in dev mode.

Environment variable: QUARKUS_ELASTICSEARCH_DEVSERVICES_SHARED

Show more

boolean

true

The value of the quarkus-dev-service-elasticsearch label attached to the started container.

This property is used when shared is set to true. In this case, before starting a container, Dev Services for Elasticsearch looks for a container with the quarkus-dev-service-elasticsearch label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise it starts a new container with the quarkus-dev-service-elasticsearch label set to the specified value.

This property is used when you need multiple shared Elasticsearch servers.

Environment variable: QUARKUS_ELASTICSEARCH_DEVSERVICES_SERVICE_NAME

Show more

string

elasticsearch

Whether to keep Dev Service containers running after a dev mode session or test suite execution to reuse them in the next dev mode session or test suite execution.

Within a dev mode session or test suite execution, Quarkus will always reuse Dev Services as long as their configuration (username, password, environment, port bindings, …​) did not change. This feature is specifically about keeping containers running when Quarkus is not running to reuse them across runs.

This feature needs to be enabled explicitly in testcontainers.properties, may require changes to how you configure data initialization in dev mode and tests, and may leave containers running indefinitely, forcing you to stop and remove them manually. See this section of the documentation for more information.

This configuration property is set to true by default, so it is mostly useful to disable reuse, if you enabled it in testcontainers.properties but only want to use it for some of your Quarkus applications.

Environment variable: QUARKUS_ELASTICSEARCH_DEVSERVICES_REUSE

Show more

boolean

true

Environment variables that are passed to the container.

Environment variable: QUARKUS_ELASTICSEARCH_DEVSERVICES_CONTAINER_ENV

Show more

Map<String,String>

Related content