Using Solr

Solr is a popular enterprise search platform build on Apache Lucene. It’s popular for its reliability, scalability, and fault tolerance. Read more about it here.

Although Elasticsearch is the default search engine that ships with Liferay DXP, it’s perfectly valid to use Solr instead. In particular, if you’ve already been using Solr with a previous version of Liferay DXP, or your deployment system (for example, your OS or JVM) isn’t supported by Elasticsearch, you might choose to use Solr to search and index your Liferay DXP data.

Liferay’s support for Solr is compatible with Solr versions 5.2.x through 5.5.x. To make Liferay DXP and Solr talk to each other, you’ll need to install the Liferay Solr adapter. There are two ways to do this:

1. Navigate to the Liferay Marketplace website and download the LPKG file for Liferay (CE) Solr 5 Search Engine. Once you do, copy the LPKG to your Liferay_Home/osgi/marketplace folder.

2. In your running Liferay instance, navigate to Control Panel → Apps → Store. Sign in using your credentials, search for Solr Search Engine, and purchase (it’s free) the Liferay (CE) Solr 5 Search Engine entry.

This guide leads you through the process of installing and configuring Solr. As you proceed, these terms will be useful to keep in mind:

Solr Home: The center of the Solr system (pun intended). This directory is solr-[version]/server/solr.

Liferay Home: The root folder of your Liferay DXP installation. It contains the osgi, deploy, data, and license folders, among others.

Before configuring Liferay DXP for Solr, you need to install and set up Solr.

Installing and Configuring Solr 5

To install and properly configure Solr for Liferay DXP:

1. Download Solr and unzip it.

2. Navigate to solr-[version]/server/solr. This is Solr Home.

3. Create a new folder called liferay.

4. In the liferay folder, create two new folders: conf and data.

5. Copy the contents of Solr_Home/configsets/data_driven_schema_configs/conf to Solr_Home/liferay/conf.

6. Open the Liferay Solr Adapter’s LPKG file with an archive manager.

   Open the com.liferay.portal.search.solr.jar file, and extract

    META-INF/resources/solrconfig.xml
   

   and

    META-INF/resources/schema.xml
   

   to

    Solr_Home/liferay/conf
   

   This replaces the current solrconfig.xml and schema.xml files with ones that tell Solr how to index data coming from Liferay DXP.

7. Create a core.properties file in Solr_Home/liferay, and add these contents:

    config=solrconfig.xml
    dataDir=data
    name=liferay
    schema=schema.xml
   

8. Checkpoint: your Solr_Home/liferay folder should now have this structure:

    liferay
    ├── conf
    │   ├── currency.xml
    │   ├── elevate.xml
    │   ├── lang
    │   ├── managed-schema
    │   ├── params.json
    │   ├── protwords.txt
    │   ├── schema.xml
    │   ├── solrconfig.xml
    │   ├── stopwords.txt
    │   └── synonyms.txt
    ├── core.properties
    └── data
   

9. Start the Solr server by entering

    ./bin/solr start -f
   

   from the top-level folder of your Solr installation (solr-[version]).

10. The Solr server listens on port 8983 by default. Navigate to http://localhost:8983/solr/#/~cores (assuming you’re testing locally with localhost as your host), and confirm that the liferay core is available.

Solr is now installed. Next install and configure Liferay DXP’s Solr adapter.

Installing and Configuring the Liferay Solr Adapter

Since Elasticsearch is the default search engine in Liferay DXP, the Elasticsearch adapter is already installed and running. Stop it before configuring the Solr adapter.

Stop the Elasticsearch adapter bundle using the App Manager, the Felix Gogo shell, or the bundle blacklist. If you’re a Digital Enterprise customer, use the blacklist feature as described below. The App Manager and Gogo shell rely on the osgi/state folder to “remember” the state of the bundle. If you delete this folder (recommended during patching) the Elasticsearch connector will be reinstalled and started automatically.

Navigate to Control Panel → Apps → App Manager.

Once you’re in the App Manager, search for elasticsearch. Find the Liferay Portal Search Elasticsearch module and click the edit (()) button. Choose the Deactivate option. This leaves the bundle installed, but stops it in the OSGi runtime.

Alternatively, use the Felix Gogo shell to stop the Elasticsearch adapter. First, open a Gogo shell and enter

lb elasticsearch

You’ll see an active bundle named Liferay Portal Search Elasticsearch (version) listed in the Gogo shell.

ID |State      |Level|Name
239|Active     |   10|Liferay Portal Search Elasticsearch (2.0.4)

Stop the Elasticsearch adapter by entering

stop [bundle ID]

In the case above, the [bundle ID] is 239.

Liferay Digital Enterprise: Digital Enterprise customers should blacklist the Elasticsearch, Shield, and Marvel plugins.

1. Create a

   com.liferay.portal.bundle.blacklist.internal.BundleBlacklistConfiguration.config
   

   file with these contents:

   blacklistBundleSymbolicNames=["com.liferay.portal.search.elasticsearch","com.liferay.portal.search.elasticsearch.shield","com.liferay.portal.search.elasticsearch.marvel.web"]
   

2. Place the file in Liferay Home/osgi/configs.

Now you can install and configure the Solr adapter:

1. Start Liferay DXP, then deploy the Solr adapter by copying the LPKG you downloaded to Liferay_Home/deploy.

   You’ll see a STARTED message in your Liferay DXP log once the solr adapter is installed. Here’s what the log message looks like:

    08:48:24,165 INFO [localhost-startStop-1][BundleStartStopLogger:35] STARTED
    com.liferay.portal.search.solr_2.0.3 [47]
   

2. To reindex against Solr, navigate to Control Panel → Configuration → Server Administration, and click Execute next to the Reindex all search indexes option.

   

   Figure 1: Once the Solr adapter is installed, you can reindex your Liferay DXP data against your Solr server.

In production deployments, specify your edits to the Solr adapter’s default configurations using a configuration file deployed to the Liferay_Home/osgi/configs folder. Name the file

com.liferay.portal.search.solr.configuration.SolrConfiguration.config

During testing and development, the System Settings app in Liferay DXP’s Control Panel → Configuration section is convenient for editing the default configurations.

Figure 2: You can configure Solr from Liferay DXP's System Settings application. This is most useful during development and testing.

High Availability with SolrCloud

You can use SolrCloud if you need a cluster of Solr servers featuring fault tolerance and high availability. Note that to use SolrCloud in production, you should set up an external ZooKeeper ensemble. ZooKeeper is a centralized coordination service for managing distributed systems, such as your SolrCloud cluster.

The steps included here should be considered the bare minimum of what must be done to configure SolrCloud with Liferay DXP. For example, these instructions cover configuring SolrCloud on a single machine, whereas a production environment would feature multiple physical or virtual machines. These instructions also assume you’ve followed the earlier section on Installing and Configuring Solr 5. Refer to the SolrCloud guide for more information.

1. Stop the Solr server if it’s running.

2. Navigate to the Solr_Home/configsets folder and create a folder called

    liferay_configs
   

3. Copy the conf folder from Solr_Home/liferay to the liferay_configs folder you just created.

   The configset/liferay_configs folder is used to configure the SolrCloud Liferay DXP collection, and is uploaded to ZooKeeper. By copying the conf folder from the liferay server configured earlier, you’re using the schema.xml and solrconfig.xml files provided with the Liferay Solr Adapter.

4. Next launch an interactive SolrCloud session to configure your SolrCloud cluster. Use this command:

    ./bin/solr -e cloud
   

5. Complete the setup wizard. These steps demonstrate creating a two-node cluster:

   • Enter 2 for the number of nodes.

   • Specify ports 8983 and 7574 (the defaults). Both nodes are started with the start commands printed in the log:

          Starting up SolrCloud node1 on port 18983 using command:
     
          solr start -cloud -s example/cloud/node1/solr -p [port#]  -m 512m
     

   • Name the collection liferay.

   • Split the collection into two shards.

   • Specify two replicas per shard.

   • When prompted to choose a configuration, enter liferay_configs. You should see a log message that concludes like this when the cluster has been started:

          SolrCloud example running, please visit http://localhost:8983/solr
     

Now you have a new collection called liferay in your local SolrCloud cluster. Verify its status by running the status command:

./bin/solr status

You’ll see log output like this:

Found 2 Solr nodes: 

Solr process 12755 running on port 7574
{
  "solr_home":"/home/russell/Documents/docs-projects/solr-docs/solr-5.2.1/example/cloud/node2/solr/",
  "version":"5.2.1 1684708 - shalin - 2015-06-10 23:20:13",
  "startTime":"2016-08-19T18:11:27.087Z",
  "uptime":"0 days, 0 hours, 13 minutes, 2 seconds",
  "memory":"50 MB (%10.2) of 490.7 MB",
  "cloud":{
    "ZooKeeper":"localhost:9983",
    "liveNodes":"2",
    "collections":"1"}}


Solr process 12564 running on port 8983
{
  "solr_home":"/home/russell/Documents/docs-projects/solr-docs/solr-5.2.1/example/cloud/node1/solr/",
  "version":"5.2.1 1684708 - shalin - 2015-06-10 23:20:13",
  "startTime":"2016-08-19T18:11:21.637Z",
  "uptime":"0 days, 0 hours, 13 minutes, 8 seconds",
  "memory":"44.9 MB (%9.2) of 490.7 MB",
  "cloud":{
    "ZooKeeper":"localhost:9983",
    "liveNodes":"2",
    "collections":"1"}}

To stop Solr while running in SolrCloud mode, use the stop command, like this:

bin/solr stop -all

Configure the Solr Adapter for SolrCloud

There’s only one thing left to do: specify the client type as CLOUD in Liferay’s Solr adapter.

1. From System Settings or your OSGi configuration file, set the Client Type to CLOUD.

    clientType="CLOUD"
   

2. Start Liferay DXP if it’s not running already.

Note: For a complete list of settings available in the Solr adapter, see the Solr Settings reference article.

Now you’re able to configure Liferay DXP for Solr, and Solr for Liferay DXP. Remember that Elasticsearch is the default search engine for Liferay DXP, so if you’re not constrained to use Solr or already a Solr expert, consider Elasticsearch for you search engine requirements. If you do use Solr, then you can tell all your colleagues that your Liferay DXP installation’s search capability is Solr powered (pun intended).