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:
Create a configuration file named
com.liferay.portal.bundle.blacklist.internal.BundleBlacklistConfiguration.config
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"]
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.apicom.liferay.portal.search.elasticsearch7.implcom.liferay.portal.search.elasticsearch7.spicom.liferay.portal.search.tuning.web.apicom.liferay.portal.search.tuning.webcom.liferay.portal.search.tuning.rankings.webcom.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,
Navigate to Control Panel → Apps → App Manager.
Once in the App Manager, search for elasticsearch. Find the Liferay Connector to Elasticsearch 7 modules and open the 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,
Enter
lb -s | grep 'search' | grep 'elasticsearch|tuning'You’ll see several active bundles for the connector to Elasticsearch and the search tuning modules.
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:
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.
Liferay 7.3: Solr 8.6.3)
Liferay 7.2: Solr 7.5.0
Navigate to Solr Home (
solr-[version]/server/solr) and create a new folder calledliferay.Create two new subfolders:
liferay/confandliferay/data.Copy the contents of
Solr_Home/configsets/_default/conftoSolr_Home/liferay/conf.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.jarfile, and extractMETA-INF/resources/solrconfig.xml
and
META-INF/resources/schema.xml
to
Solr_Home/liferay/conf
This replaces the current
solrconfig.xmlandschema.xmlfiles with ones that tell Solr how to index data coming from Liferay.Create a
core.propertiesfile inSolr_Home/liferayand add this configuration:config=solrconfig.xml dataDir=data name=liferay schema=schema.xml
Checkpoint: your
Solr_Home/liferayfolder 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
Start the Solr server by entering the following from the top-level folder of your Solr installation (
solr-[version]):./bin/solr start -f
The Solr server listens on port
8983by default. Navigate to http://localhost:8983/solr/#/~cores (assuming you’re testing locally withlocalhostas your host), and confirm that theliferaycore 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.
Liferay CE: Liferay CE Connector to Solr 8
Liferay DXP: Liferay Connector to Solr 8
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:
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.
Once the app LPKG is downloaded, copy it to
Liferay_Home/osgi/marketplaceand put any configuration files inLiferay_Home/osgi/configs.Start Liferay.
Re-index your Liferay data into Solr. Open the Global Menu and navigate to Control Panel → Configuration → Search. In the Index Actions pane, click Execute next to the Reindex all search indexes option.
Re-index the spell check indexes too.
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.
Stop the Solr server if it’s running.
Navigate to the
Solr_Home/configsetsfolder and create a folder calledliferay_configsCopy the
conffolder fromSolr_Home/liferayto theliferay_configsfolder you just created.The
configset/liferay_configsfolder contains the SolrCloud Liferay collection configuration and is uploaded to ZooKeeper. When you copy theconffolder from theliferayserver configured earlier, you use theschema.xmlandsolrconfig.xmlfiles provided with the Liferay Solr Adapter.Launch an interactive SolrCloud session to configure your SolrCloud cluster:
./bin/solr -e cloud
Complete the setup wizard. These steps demonstrate creating a two-node cluster:
Enter
2for the number of nodes.Specify ports
8983and7574(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.
From System Settings or your OSGi configuration file, set the Client Type to CLOUD.
clientType="CLOUD"
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.
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.