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 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:
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 environment variables:
| Property | Default Value | Description |
|---|---|---|
| DOT_ES_AUTH_TYPE | BASIC | Accepted values are:
|
| DOT_ES_AUTH_BASIC_USER | admin | User name for BASIC authentication. |
| DOT_ES_AUTH_BASIC_PASSWORD | admin | Password for BASIC authentication. |
| DOT_ES_AUTH_JWT_TOKEN | See Notes | Token for JWT authentication. |
| DOT_ES_TLS_ENABLED | false | If set to true, enables TLS encryption.
|
| DOT_ES_AUTH_TLS_CLIENT_CERT | certs/elasticsearch.pem | Path (relative to the assets folder) where the client certificate is stored. |
| DOT_ES_AUTH_TLS_CLIENT_KEY | certs/elasticsearch.key | Path (relative to the assets folder) to the certificate’s key file (PKCS # 8). |
| DOT_ES_AUTH_TLS_CA_CERT | certs/root-ca.pem | Path (relative to the assets folder) where the authority certificate is stored. |
| DOT_ES_REST_CLIENT_PROVIDER_CLASS | com.dotcms.content.elasticsearch | Fully qualified name of the class of your custom client. |
Notes:
- 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.
