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. The main configuration
elasticsearch.yml, used for configuring Elasticsearch modules.
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 in
the Liferay DXP Elasticsearch connector, this works just fine. Of course, you can
name your cluster whatever you want (we humbly submit the recommendation
clustery_mcclusterface).1 Configure your node name
using the same syntax (setting the
node.name property). There’s no client
setting for this, it exists only in each Elasticsearch node’s
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 them to each other.
Configuring the Liferay Elasticsearch Connector
The Elasticsearch connector provides integration between Elasticsearch and the portal. Before configuring the connector, make sure Elasticsearch is running.
There are two ways to configure the connector:
It’s convenient to configure the Elasticsearch connector from System Settings,
but this is often only possible during development and testing. If you’re not
familiar with System Settings, read about it
Remember that you can generate configuration files for deployment to other
systems by configuring System Settings, and then exporting the
with your configuration.
Configuring the Connector in the Control Panel
To configure the Elasticsearch connector from the System Settings application,
Start Liferay DXP.
Navigate to Control Panel → Configuration → System Settings → Platform.
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 Connector with an OSGi
When preparing a system for production deployment, you want to use 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 connector using a 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-production 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 or as few 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
To cluster Elasticsearch, 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 connector,
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
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:
|Connector Setting/Operation Mode||EMBEDDED||REMOTE|
1 This is, of course, a nod to all those fans of Boaty Mcboatface.