Installing Elasticsearch

Here’s how to install, configure, and start Elasticsearch on-premises.

note

If you have Elasticsearch indexes used for primary data storage (storing data not backed by a database) you can bring that data into your new Elasticsearch cluster using the snapshot and restore approach. Liferay’s own Search Tuning indexes (for Result Rankings and Synyonyms) are primary storage indexes on Liferay DXP 7.2 and 7.3.

Environment Setup for Production-Like Installation

Adding Hosts

You can skip this if you’ll set up a testing environment using localhost or Docker containers. For a production-like setup on your local machine, add the hosts for Liferay and the Elasticsearch cluster. Add this information to your operating system’s path/to/etc/hosts file:

<your IP> es-node1
<your IP> es-node2
<your IP> es-node3
<your IP> dxp.liferay.com

Use the real IP address of your system, not the loopback address 127.0.0.1.

Adjusting mmap

Elasticsearch requires a higher mmap count (for mapping the directory holding its indexes into memory) than the default for most operating systems. On Linux and as the root user, run

sysctl -w vm.max_map_count=262144

Compatibility Headers

For Elasticsearch 8, if there is a firewall or proxy between Liferay and Elasticsearch, make sure the compatibility HTTP headers Liferay sets on each request are allowed and preserved in the network traffic. See Elasticsearch’s Requesting REST API Compatibility for more information.

Install Elasticsearch

Download an Elasticsearch archive from Elastic’s website.

important

Download the latest Elasticsearch archive compatible with your Liferay version.
Extract the archive contents to a local folder where you want to run Elasticsearch. This folder is your Elasticsearch Home.

Install the required Elasticsearch plugins by running these commands in your [Elasticsearch Home]/bin folder:

./elasticsearch-plugin install analysis-icu

./elasticsearch-plugin install analysis-kuromoji

./elasticsearch-plugin install analysis-smartcn

./elasticsearch-plugin install analysis-stempel

Configure Elasticsearch

Each Elasticsearch server is configured by its [Elasticsearch Home]/config/elasticsearch.yml file.

Here are example single-node and multi-node Elasticsearch cluster configurations.

See Securing Elasticsearch to learn about authenticating and encrypting communication with the Elasticsearch server(s).

Example: Single-Node Production Elasticsearch Cluster

Here’s an elasticsearch.yml configuration for a single-node cluster:

cluster.name: LiferayElasticsearchCluster

discovery.type: single-node
http.port: 9200
network.host: es-node1
node.name: es-node1
transport.port: 9300

# Add security settings below
xpack.security.enabled: false

# Uncomment for Liferay versions prior to DXP 2024.Q2/Portal GA120. This
# disables index auto-creation for indexes prefixed with 'liferay-'
# action.auto_create_index:"-liferay-*

Note

Liferay DXP 2024.Q2+/Portal 7.4 GA120+ automatically disables index auto-creation in Elasticsearch for indexes prefixed with liferay- and any defined custom index name prefix.

This cluster called LiferayElasticsearchCluster has one node called es-node1.

tip

If you are not configuring hosts for a production mode setup, use localhost as the host value. Elasticsearch can bind to loopback addresses for HTTP and Transport communication. Along with single node discovery, this means the Elasticsearch server is running in development mode.

Example: Multi-Node Production Elasticsearch Cluster

Here is an elasticsearch.yml for a node called es-node3 of a three-node cluster:

cluster.name: LiferayElasticsearchCluster

# Example production mode settings - 3-node cluster
cluster.initial_master_nodes:
  - es-node1
  - es-node2
  - es-node3
discovery.seed_hosts:
  - es-node1:9300
  - es-node2:9301
  - es-node3:9302
http.port: 9202
network.host: es-node3
node.name: es-node3
transport.port: 9302

# Add security settings below
xpack.security.enabled: false

# With Liferay versions prior to DXP 2024.Q2/Portal GA120, uncomment to disable
# index auto-creation for indexes prefixed with 'liferay-'
# action.auto_create_index:"-liferay-*

Note

Liferay DXP 2024.Q2+/Portal 7.4 GA120+ automatically disables index auto-creation in Elasticsearch for indexes prefixed with liferay- and any defined custom index name prefix.

Tip

Start Elasticsearch

Start Elasticsearch from the bin folder:

./elasticsearch

tip

If Elasticsearch fails to start with the ERROR message Elasticsearch exited unexpectedly in the log, increase the heap size. During testing you can open the config/jvm.options file and uncomment the example settings for -Xms4g and -Xmx4g. In production, follow the instructions in that file to set these parameters properly.

See Troubleshooting Elasticsearch Installation for more information.

Elasticsearch starts, and one of its status messages includes a transport address:

[2019-04-01T16:55:50,127][INFO ][o.e.t.TransportService   ] [HfkqdKv] publish_address {127.0.0.1:9300}, bound_addresses {[::1]:9300}, {127.0.0.1:9300}

If you’re running Liferay 7.2, note the publish_address address in the TransportService status message; you must configure the Liferay servers to connect to Elasticsearch at this address.

Elasticsearch is ready for connections from Liferay.

If you’re running in production, secure communication between Liferay and Elasticsearch.