For detailed Elasticsearch configuration information, refer to the Elasticsearch documentation.
The name of your Elasticsearch cluster is important. When you’re running Elasticsearch in remote mode, the cluster name is used by Liferay DXP to recognize the Elasticsearch cluster. To learn about setting the Elasticsearch cluster name on the Liferay DXP side, refer below to the section called Configuring the Liferay Elasticsearch Connector.
Elasticsearch’s configuration files are written in YAML
and kept in the
[Elasticsearch Home]/config folder:
elasticsearch.ymlis for configuring Elasticsearch modules
logging.ymlis for configuring Elasticsearch logging
To set the name of the Elasticsearch cluster, open
[Elasticsearch Home]/config/elasticsearch.yml and specify
LiferayElasticsearchCluster is the default name given to the cluster,
this would work just fine. Of course, you can name your cluster whatever you’d
like (we humbly submit the recommendation
clustery_mcclusterface).1 You can configure your node
name using the same syntax (setting the
If you’d rather work from the command line than in the configuration file, navigate to Elasticsearch Home and enter
./bin/elasticsearch --cluster.name clustery_mcclusterface --node.name nody_mcnodeface
Feel free to change the node name or the cluster name. Once you configure Elasticsearch to your liking, start it up.
Start Elasticsearch by navigating to Elasticsearch Home and typing
if you run Linux, or
if you run Windows.
To run as a daemon in the background, add the
-d switch to either command:
Once both Elasticsearch and Liferay DXP are installed and running, introduce Liferay DXP and Elasticsearch to each other.
Configuring the Liferay Elasticsearch Connector
The Elasticsearch connector provides integration between Elasticsearch and Liferay DXP. Before you configure the connector, make sure Elasticsearch is running.
There are two ways to configure the adapter:
It’s convenient to configure the Elasticsearch adapter from System Settings, but
this is often only possible during development and testing. If you’re not
familiar with System Settings, you can read about it
here. Remember that you
can generate configuration files for deployment to other systems by configuring
System Settings, and then exporting the
.config file with your configuration.
Configuring the Adapter in the Control Panel
Here’s how to configure the Elasticsearch adapter from the System Settings application:
Start Liferay DXP.
Navigate to Control Panel → Configuration → System Settings → Foundation.
Find the Elasticsearch entry (scroll down and browse to it or use the search box) and click the Actions icon (), then Edit.
Make any edits to the configuration and click Save.
Configuring the Adapter with an OSGi
When preparing a system for production deployment, you should have a repeatable deployment process. Therefore, it’s best to use the OSGi configuration file, where your configuration is maintained in a controlled source.
Follow these steps to configure the Elasticsearch adapter using an OSGi configuration file:
Create the following file:
Add configurations to the file, in the format
propertyName="Value". For example,
operationMode="REMOTE" # If running Elasticsearch from a different computer: #transportAddresses="ip.of.elasticsearch.node:9300" # Highly recommended for all non-prodcution usage (e.g., practice, tests, diagnostics): #logExceptionsOnly="false"
Start Liferay DXP or re-index if already running.
As you can see from the System Settings entry for Elasticsearch, there are a lot more configuration options available that help you tune your system for optimal performance.
What follows here are some known good configurations for clustering Elasticsearch. These, however, can’t replace the manual process of tuning, testing under load, and tuning again, so we encourage you to examine the
Elasticsearch documentation and go through that process once you have a working configuration.
Configuring a Remote Elasticsearch Host
In production systems Elasticsearch and Liferay DXP are installed on different servers. To make Liferay DXP aware of the Elasticsearch cluster, set
transportAddresses=[IP address of Elasticsearch Node]:9300
Here’s an example that sets the IP address of two nodes in the Elasticsearch cluster:
Set this in the Elasticsearch connector’s OSGi configuration file. List as many Elasticsearch nodes in this property as you want. This tells Liferay DXP the IP address or host name where search requests should be sent. If using System Settings, set the value in the Transport Addresses property.
On the Elasticsearch side, set the
network.host property in your
elaticsearch.yml file. This property simultaneously sets both the bind host
(the host where Elasticsearch listens for requests) and the publish host
(the host name or IP address Elasticsearch uses to communicate with other
for more information.
Clustering Elasticsearch in Remote Operation Mode
Clustering Elasticsearch is easy. First, set
be something greater than
1. When you run the Elasticsearch start script,
a new local storage node is added to the cluster. If you want four nodes running
locally, for example, run
./bin/elasticsearch four times. See
for more information.
Configure the number of shards and replicas in the Elasticsearch 6 adapter,
indexNumberOfReplicas properties to
specify the number of primary shards and number of replica shards, respectively.
Elasticsearch’s default configuration works for a cluster of up to ten nodes,
since the default number of shards is
5 and the default number of replica
For more information on configuring an Elasticsearch cluster, see the documentation on Elasticsearch Index Settings.
Elasticsearch Connector System Settings, By Operation Mode
Some of the settings available for the Elasticsearch connector are applicable for only one operation mode (REMOTe or EMBEDDED). Refer to the table below:
|Adapter Setting/Operation Mode||EMBEDDED||REMOTE|
* Note: Available in the Connector to Elasticsearch 6 only.
1 This is, of course, a nod to all those fans of Boaty Mcboatface.