Custom Elasticsearch REST Client 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:

RestHighLevelClientProvider.getInstance()

Setting the Client

To set the REST client via configuration, modify the following property in the dotcms-config-cluster.properties file:

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:

RestHighLevelClientProvider.getInstance().setClient(yourCustomClient);

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 properties in the dotcms-config-cluster.properties file:

PropertyDefault ValueDescription
ES_AUTH_TYPEBASICAccepted values are:
  • BASIC
    • When this is set, credentials must be set through the properties ES_AUTH_BASIC_USER and ES_AUTH_BASIC_PASSWORD.
  • JWT
    • When this is set, a valid token (ES_AUTH_JWT_TOKEN property) must be set.
ES_AUTH_BASIC_USERadminUser name for BASIC authentication.
ES_AUTH_BASIC_PASSWORDadminPassword for BASIC authentication.
ES_AUTH_JWT_TOKENSee NotesToken for JWT authentication.
ES_TLS_ENABLEDfalseIf set to true, enables TLS encryption.
  • When true, certificates must be specified (ES_AUTH_TLS_CLIENT_CERT, ES_AUTH_TLS_CLIENT_KEY, and ES_AUTH_TLS_CA_CERT)
ES_AUTH_TLS_CLIENT_CERTcerts/elasticsearch.pemPath (relative to the assets folder) where the client certificate is stored.
ES_AUTH_TLS_CLIENT_KEYcerts/elasticsearch.keyPath (relative to the assets folder) to the certificate’s key file (PKCS # 8).
ES_AUTH_TLS_CA_CERTcerts/root-ca.pemPath (relative to the assets folder) where the authority certificate is stored.
ES_REST_CLIENT_PROVIDER_CLASScom.dotcms.content.elasticsearch
.util.DotRestHighLevelClient
Fully qualified name of the class of your custom client.

Notes:

  • It is strongly recommended that all changes to the dotcms-config-cluster.properties file be made through a ROOT Folder Plugin.
  • 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 RestClientProvider and deliver your own custom configured RestClient. 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.