Documentation

Installing Solr

These instructions describe installing Solr 8 for Liferay 7.3. They apply equally to installing Solr 7 for Liferay 7.2, but some adjustments for version name may be necessary.

Important

  • Liferay’s Solr support is deprecated; Solr 8 is the last supported Solr version. Please plan to migrate to Elasticsearch.

  • There are important limitations to be aware of when installing Solr. Read Solr Limitations before proceeding with the installation.

Solr is a popular enterprise search platform built on Apache Lucene. It’s reliable, scalable, and fault tolerant. Read more about it here.

See the Search Engine Compatibility Matrix for more detailed information on Liferay’s search engine support.

As you proceed, remember these terms:

Solr Home: Refers to solr-[version]/server/solr/, the main Solr configuration directory. This is where the Liferay core will be configured.

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

Disabling Elasticsearch-Only Features

Before installing the Liferay Connector to Solr, you must blacklist or otherwise disable

  • the modules for certain DXP features that only work with Elasticsearch

  • the Liferay Connector to Elasticsearch’s modules

Tip

Use the Gogo shell command lb [substring-to-search] -s to search for modules deployed to the OSGi runtime and list them by their Symbolic Name. The Symbolic Name is the value to enter in the blacklistBundleSymbolicNames property.

The following command returns the list of modules that must be blacklisted:

lb -s | grep 'search' | grep 'elasticsearch|tuning'

Blacklisting Elasticsearch-Only Features

If you’re a Liferay DXP customer you should use the blacklist feature to disable the Elasticsearch-only features. CE users can also use this approach:

  1. Create a configuration file named

    com.liferay.portal.bundle.blacklist.internal.BundleBlacklistConfiguration.config
    
  2. Give it these contents:

    blacklistBundleSymbolicNames=["com.liferay.portal.search.elasticsearch7.api","com.liferay.portal.search.elasticsearch7.impl","com.liferay.portal.search.elasticsearch7.spi","com.liferay.portal.search.tuning.rankings.web","com.liferay.portal.search.tuning.synonyms.web","com.liferay.portal.search.tuning.web","com.liferay.portal.search.tuning.web.api"]
    
  3. Place the file in Liferay Home/osgi/configs.

    Here’s the complete list of apps and bundles you’re disabling:

    • com.liferay.portal.search.elasticsearch7.api

    • com.liferay.portal.search.elasticsearch7.impl

    • com.liferay.portal.search.elasticsearch7.spi

    • com.liferay.portal.search.tuning.web.api

    • com.liferay.portal.search.tuning.web

    • com.liferay.portal.search.tuning.rankings.web

    • com.liferay.portal.search.tuning.synonyms.web

Stopping the Modules with Elasticsearch-Only Features

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 Liferay DXP) the Elasticsearch connector is reinstalled and started automatically. Liferay CE users can use the blacklist approach or disable the Elasticsearch and search tuning modules in the App Manager or the Gogo shell.

To disable via App Manager,

  1. Navigate to Control Panel → Apps → App Manager.

  2. Once in the App Manager, search for elasticsearch. Find the Liferay Connector to Elasticsearch 7 modules and open the Actions (Actions) menu. Choose Deactivate. This leaves the bundle installed, but stops it in the OSGi runtime. Do the same for the search tuning modules.

To use the Felix Gogo shell to stop the Elasticsearch and search tuning modules,

  1. Enter lb -s | grep 'search' | grep 'elasticsearch|tuning'

    You’ll see several active bundles for the connector to Elasticsearch and the search tuning modules.

  2. For each bundle listed enter stop [bundle ID].

Installing and Configuring Solr

Before proceeding, stop the Liferay instance.

To install and properly configure Solr for Liferay:

  1. Download a compatible Solr and unzip it. The below links are for convenience only and represent the latest compatible Solr version at the time of writing. See the Search Engine Compatibility Matrix to see if newer compatible versions are available.

  2. Navigate to Solr Home (solr-[version]/server/solr) and create a new folder called liferay.

  3. Create two new subfolders: liferay/conf and liferay/data.

  4. Copy the contents of Solr_Home/configsets/_default/conf to Solr_Home/liferay/conf.

  5. Open the Liferay Connector to Solr 8’s LPKG file with an archive manager.

    Next open the Liferay Connector to Solr 8 - Impl.lpkg.

    Finally, open the com.liferay.portal.search.solr8.impl.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.

  6. Create a core.properties file in Solr_Home/liferay and add this configuration:

    config=solrconfig.xml
    dataDir=data
    name=liferay
    schema=schema.xml
    
  7. Checkpoint: your Solr_Home/liferay folder now has this structure:

    liferay
    ├── conf
    │   ├── lang
    │   │   ├── contractions_ca.txt
    │   │   ├── ....txt
    │   ├── managed-schema
    │   ├── protwords.txt
    │   ├── schema.xml
    │   ├── solrconfig.xml
    │   ├── stopwords.txt
    │   └── synonyms.txt
    ├── core.properties
    └── data
    
  8. Start the Solr server by entering the following from the top-level folder of your Solr installation (solr-[version]):

    ./bin/solr start -f
    
  9. 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 and started. Next configure and install the Solr connector for Liferay.

Installing the Solr Connector

To install the Liferay Connector to Solr [7 or 8], navigate to Liferay Marketplace and download the app version that corresponds to your Liferay version.

The default connector configuration works for a test installation because the default configurations in the Liferay Connector to Solr match Solr’s own defaults. See the Configuration Reference for the complete list of available settings. At a minimum, the read and write URLs must be configured for the connector in production environments.

In production deployments it’s most common to make your edits to the Solr connector’s default configurations using a configuration file deployed to the Liferay_Home/osgi/configs folder:

  1. Name the file

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

You can alternatively use the UI for configuring the connector. Find the Solr 7 System Settings entry in Control Panel → Configuration → System Settings.

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

  1. Once the app LPKG is downloaded, copy it to Liferay_Home/osgi/marketplace and put any configuration files in Liferay_Home/osgi/configs.

  2. Start Liferay.

  3. Re-index your Liferay data into Solr. Open the Global Menu and navigate to Control PanelConfigurationSearch. In the Index Actions pane, click Execute next to the Reindex all search indexes option.

    Re-index the spell check indexes too.

    The Solr connection can be verified in the Search administration console.

High Availability with SolrCloud

Use SolrCloud if you need a cluster of Solr servers. 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 like your SolrCloud cluster.

The steps included here should be considered the bare minimum of what must be done to configure SolrCloud with Liferay. 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. 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 contains the SolrCloud Liferay collection configuration and is uploaded to ZooKeeper. When you copy the conf folder from the liferay server configured earlier, you use the schema.xml and solrconfig.xml files provided with the Liferay Solr Adapter.

  4. Launch an interactive SolrCloud session to configure your SolrCloud cluster:

    ./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 Solr on port 8983 using command:
      "bin/solr" start -cloud -p 8983 -s "example/cloud/node1/solr"
      
      Waiting up to 180 seconds to see Solr running on port 8983 [|]  [-]  
      Started Solr server on port 8983 (pid=8846). Happy searching!
      
      
      Starting up Solr on port 7574 using command:
      "bin/solr" start -cloud -p 7574 -s "example/cloud/node2/solr" -z localhost:9983
      
      Waiting up to 180 seconds to see Solr running on port 7574 [|]  [/]  
      Started Solr server on port 7574 (pid=9026). Happy searching!
      
    • 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

The log output states that the nodes are found and lists information for each node:

Found 2 Solr nodes: 

Solr process 223597 running on port 8983
{
  "solr_home":"/home/user/liferay-bundles/solr8_7.3/solr-8.6.3/example/cloud/node1/solr",
  "version":"8.6.3 e001c2221812a0ba9e9378855040ce72f93eced4 - jasongerlowski - 2020-10-03 18:12:03",
  "startTime":"2021-03-23T18:26:45.450Z",
  "uptime":"0 days, 0 hours, 25 minutes, 4 seconds",
  "memory":"306.5 MB (%59.9) of 512 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 connector.

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

    clientType="CLOUD"
    
  2. Start Liferay if it’s not running already. If this is the first time starting after installing the Solr connector LPKG, follow the instructions in the log to restart Liferay again.

From the Solr System Settings entry, set the Client Type to Cloud.

Solr Connector Configuration Reference

Below are the default configurations along with settings that become available (in the System Settings Search category, or configurable by .config file) when you install the Solr connector application. These settings accept a limited set of values:

Configuration File: com.liferay.portal.search.solr8.configuration.SolrConfiguration.config
System Settings Entry: Solr 8

authenticationMode=["BASIC" or "CERT"]
clientType=["REPLICATED" or "CLOUD"]
defaultCollection="liferay"
logExceptionsOnly=B"true"
readURL="http://localhost:8983/solr/liferay"
writeURL="http://localhost:8983/solr/liferay"
zkHost="localhost:9983"

Configuration File: com.liferay.portal.search.solr8.configuration.SolrHttpClientFactoryConfiguration.config
System Settings Entry: Solr 8 HTTP Client Factory

basicAuthPassword="solr"
basicAuthUserName="solr"
defaultMaxConnectionsPerRoute="20"
maxTotalConnections="20"

Configuration File: com.liferay.portal.search.solr8.configuration.SolrSSLSocketFactoryConfiguration.config
System Settings Entry: Solr 8 SSL Factory

keyStorePassword="secret"
keyStorePath="classpath:/keystore.jks"
keyStoreType="JKS"
trustStorePassword="secret"
trustStorePath="classpath:/truststore.jks"
trustStoreType="JKS"
verifyServerCertificate=B"true"
verifyServerName=B"true"

Now you can configure Liferay for Solr and Solr for Liferay. Remember that Solr is deprecated. If you’re not constrained to use Solr or already a Solr expert, use Elasticsearch.