Custom Elasticsearch REST Client

Last Updated: Jan 22, 2024
documentation for the dotCMS Content Management System

You may provide your own Elasticsearch REST client, to enable custom behavior for your dotCMS implementation. For example, you may create a client that will fail over to another ES cluster if the primary is not available, provide load balancing, or support custom connection parameters not supported by the Elasticsearch REST client provided by dotCMS.

Getting and Setting the REST Client

Getting the Client

To retrieve the REST client from Java code, call the following method:


Setting the Client

To set the REST client via configuration, modify the following environment variable:

DOT_ES_REST_CLIENT_PROVIDER_CLASS={fully qualified name of the class}

To change the REST Client at runtime (e.g. via a plugin), call the following method:


The Default REST Client

By default, a high level rest client is provided (com.dotcms.content.elasticsearch.util.DotRestHighLevelClient), which supports two authentication types (BASIC and JWT), allows the use of TLS certificates for REST API and transport encryption.

This default client can be configured using the following environment variables:

PropertyDefault ValueDescription
DOT_ES_AUTH_TYPEBASICAccepted values are:
    • When this is set, credentials must be set through the properties DOT_ES_AUTH_BASIC_USER and DOT_ES_AUTH_BASIC_PASSWORD.
  • JWT
    • When this is set, a valid token (DOT_ES_AUTH_JWT_TOKEN property) must be set.
DOT_ES_AUTH_BASIC_USERadminUser name for BASIC authentication.
DOT_ES_AUTH_BASIC_PASSWORDadminPassword for BASIC authentication.
DOT_ES_AUTH_JWT_TOKENSee NotesToken for JWT authentication.
DOT_ES_TLS_ENABLEDfalseIf set to true, enables TLS encryption.
  • When true, certificates must be specified (DOT_ES_AUTH_TLS_CLIENT_CERT, DOT_ES_AUTH_TLS_CLIENT_KEY, and DOT_ES_AUTH_TLS_CA_CERT)
DOT_ES_AUTH_TLS_CLIENT_CERTcerts/elasticsearch.pemPath (relative to the assets folder) where the client certificate is stored.
DOT_ES_AUTH_TLS_CLIENT_KEYcerts/elasticsearch.keyPath (relative to the assets folder) to the certificate’s key file (PKCS # 8).
DOT_ES_AUTH_TLS_CA_CERTcerts/root-ca.pemPath (relative to the assets folder) where the authority certificate is stored.
Fully qualified name of the class of your custom client.


  • It is strongly recommended that all changes to system properties be made through environment variables.
  • You should always generate your own JWT token, and configure your Elasticsearch server to accept that token.
    • The default token is valid only with the dotCMS custom Elasticsearch open distro image.

Custom REST Clients

You can write your own RestHighLevelClientProvider and deliver your own custom configured REST client. For sample code to use as a basis for your own client, please see the dotCMS Github Repo.

Once you have created your own client, you can set the client for dotCMS to use via either configuration or Java code.

On this page


We Dig Feedback

Selected excerpt: