Elasticsearch Configuration

dotCMS requires an Elasticseach node or cluster to index and search the stored content, the file metadata and also in order to perform site wide searches. It is important to note that dotCMS does not automatically manage the Elasticsearch cluster - you must perform management functions yourself to ensure proper operation of the Elasticsearch infrastructure. That said, generally speaking, an elasticsearch cluster that is dedicated to dotCMS does not require much care or feeding aside from consuming memory and disk space and many dotCMS instances run happily for years against a single node ES installation or container given enough disk space.

Configuration

To connect dotCMS to an elasticsearch cluster you should specify at least 3 environmental variables:

DOT_ES_ENDPOINTS=https://es1.dotcmssite.com:9200
DOT_ES_AUTH_BASIC_USER=admin
DOT_ES_AUTH_BASIC_PASSWORD={yourSecretPassword}

• DOT_ES_ENDPOINTS takes a comma separated list of urls that it will connect and load balance search requests to. The property can look like this

  "DOT_ES_ENDPOINTS": 'https://es1.dotcmssite.com:9200'
  

  or contain multiple entries, such as

  "DOT_ES_ENDPOINTS": 'https://es1.dotcmssite.com:9200,https://es2.dotcmssite.com:9200,https://es3.dotcmssite.com:9200'
  

• DOT_ES_AUTH_BASIC_USER is the basic auth username that will be sent and used to perform search and indexing operations (defaults to admin)

• DOT_ES_AUTH_BASIC_PASSWORD is the basic auth password. Best practices are to use a secret store mechanism when providing these to your container.

Other, less well used options include

• DOT_ES_AUTH_TYPE, which defaults to BASIC but can also be set to JWT JWT based authentication.
• DOT_ES_AUTH_JWT_TOKEN which can be used to pass the JWT auth token (again, use secrets).

Elasticsearch Versions

In 2021 and at version 7.10, Elastic.co changed Elasticsearch's licensing from an Apache 2.0 (pure open source) license to a proprietary license that precludes other companies from offering a hosted/managed version of Elasticsearch software. This was aimed primarily at Amazon, who had been offering an AWS managed Elasticsearch service “OpenSearch” without paying any royalites to Elastic.co. After Elastic.co changed the Elasticsearch license, Amazon forked the original open source Elasticsearch project and created a competeing version of Elasticsearch software licensed under the Apache 2.0 that they have dubbed “OpenSearch” (https://opensearch.org/). Amazon now uses the Opensearch project in all their managed “Elasticsearch” offerings.

Due to the Elasticsearch licencing change, dotCMS has decided to standardize on Amazon's OpenSearch version of Elasticseach licensed under the Apache 2.0 license rather than Elastic.co's proprietary Elasticseach version. In doing this, dotCMS upgraded the Elasticsearch drivers in our software to the last open source version of Elasticsearch provided by Elastic.co, version 7.10.2. As of this writing, we believe dotCMS continues to be compatible with all known versions of Elasticsearch > 7.1.0 whether they are offered by Elastic.co or Amazon but test and support only Amazon's OpenSearch. Moving forward, dotCMS will continue to be compatiable with OpenSearch as the OpenSearch versions progress but cannot guarentee that we will maintain version compatiability with Elastic.co's Elasticsearch offerings if they choose to include breaking changes.