How to Integrate Apache Solr with Sitecore 9.1 using SearchStax


Overview

SearchStax® can be used to enable Apache Solr on a Sitecore website.

Contents:

  1. Install Sitecore 9.1 without Solr
  2. Create a New Deployment in SearchStax.
  3. Install the Zookeeper script.
  4. Upload the Sitecore Configuration Files.
  5. Create Sitecore Collections.
  6. Configure Sitecore to use SearchStax.
  7. Populate Schema from the Control Panel.
  8. SwitchOnRebuild.

Install Sitecore 9.1 without Solr

This section describes how to install Sitecore 9.1 locally without Solr. We'll connect it to a SearchStax Solr deployment in a subsequent step.

  1. Visit the Sitecore Experience Platform 9.1 Initial Release page. Under Download Options for On Premises Deployment, download Packages for XP Single.

    SearchStax Solr Sitecore

    Under Release Information, download the Installation Guide and the Quick Installation Guide.

    SearchStax Solr Sitecore
  2. With the exception of Solr, install all the prerequisite sub-components as mentioned in the installation guide.

  3. Make the following changes in the configuration files.
    1. XP0-SingleDeveloper.ps1: Comment out or remove the Solr root and service details:
      SearchStax Solr Sitecore
    2. XP0-SingleDeveloper.json: Comment out or remove the XConnectSolr and SitecoreSolr "includes:"
      SearchStax Solr Sitecore
    3. Sitecore-XPO: Comment our or remove the UpdateSolrSchema task:
      SearchStax Solr Sitecore
    4. Xconnect-xp0: Comment out or remove the ConfigureSolrSchemas task.
      SearchStax Solr Sitecore
  4. Once all the above changes have been made, go ahead with the Sitecore installation by running the PowerShell script .\XP0-SingleDeveloper.ps1 as recommended in the Sitecore installation guide.
    SearchStax Solr Sitecore

Create a New Deployment in SearchStax

Assuming you have already created a SearchStax account and do not already have a deployment set up, click on the Cloud Manager tab and then click on the Create Deployment button at the top. Enter a deployment name, and select the most appropriate provider, region, plan, and Solr version for your needs. SearchStax Solr Sitecore

Cloud Provider

A self-managed Sitecore project may use any of our cloud providers for the Solr deployment.

Single Node or Cluster

Sitecore will work with a single-node deployment (the "DN" series of SearchStax deployments) for purposes of testing and evaluation. However, a production system requires a SearchStax cluster (the "DC" series) to provide high-availability and failover features.

Sitecore/Solr Compatibility

The following table shows Solr versions that are compatible with both Sitecore and with SearchStax. These combinations have been tested; other combinations may or may not work successfully.

Sitecore Solr
XP 8.2 5.5.0
XP 9.0 6.6.2
XP 9.1 7.2.1

Once you create your deployment, you will see it in the Solr Deployments dashboard.
SearchStax Solr Sitecore
Clicking on the name of the deployment gives you pertinent information about your deployment's servers. The Solr HTTP Endpoint takes you to your Solr server dashboard. SearchStax Solr Sitecore

Install the Zookeeper Script

Apache ZooKeeper is a centralized service for maintaining configuration information. In a SearchStax Solr deployment, Zookeeper acts as a centralized repository for your Solr configuration files.

SearchStax users do not have direct access to the Zookeeper configsets as they would in a local Solr installation. Instead, they interact with Zookeeper through a modified version of Solr's standard zkcli script. SearchStax provides both Linux and Windows versions of the script.

You can download the zkcli ZIP file here: searchstax-client-master.zip.

Unzip the file. The top-level directory is \searchstax-client-master. Navigate to the solr-5, solr-6, or solr-7 scripts subdirectory (such as \searchstax-client-master\solr-7\scripts). Locate zkcli.sh and zkcli.bat in that directory. These are the Windows and Linux versions of the script, respectively. SearchStax Client Master

Learn about zkcli

The zkcli script is an all-purpose toolkit for managing Zookeeper on a cloud deployment. See What else can I do with the zkcli script?

Upload the Sitecore Configuration Files

Follow these steps to upload the Sitecore Solr configuration to Zookeeper:

  1. Download Solr 7.2.1 and extract the file onto a local system.
  2. Locate the configset folder in solr\solr-7.2.1\server\solr.
  3. Copy/Duplicate the _default folder into to a new sitecore_configs folder.
  4. In this new folder, open the managed-schema file in the conf folder and do the following:
    1. Set the value in <uniqueKey>id</uniqueKey> to _uniqueid.
    2. In the fields section, add the following field configuration for _uniqueid:
      <field name="_uniqueid" type="string" indexed="true" required="true" stored="true"/>
  5. Use the zkcli.bat script to run this command:
    ./zkcli.bat -zkhost <zookeeper URLs> -cmd upconfig -d sitecore_configs -n sitecore 

    where <zookeeper URLs> corresponds to the URL of the Zookeeper ensemble in the deployment details page:
    Screenshot

Create Sitecore Collections

When you have uploaded the Solr configuration to Zookeeper, you can create Sitecore collections by following these steps:

  1. Navigate to the Collections page in the Solr Admin UI.
  2. Click Add Collection.
  3. In the config set field, click the Sitecore configuration.
  4. Specify the following fields as shown:
    Screenshot

    Pay attention to ReplicationFactor

    Use replicationFactor=1 for a single-node deployment. A cluster should have replicationFactor=n (where n is the number of servers in the deployment). This is essential for a high-availability cluster.

  5. Repeat for all Sitecore indexes.
    1. sitecore_master_index
    2. sitecore_core_index
    3. sitecore_web_index
    4. sitecore_marketingdefinitions_master
    5. sitecore_marketingdefinitions_web
    6. sitecore_marketing_asset_index_master
    7. sitecore_marketing_asset_index_web
    8. sitecore_testing_index
    9. sitecore_suggest_test_index
    10. sitecore_fxm_master_index
    11. sitecore_fxm_web_index

Configure Sitecore to Use SearchStax

Follow these steps to configure Sitecore to use SearchStax as the search provider:

  1. Open the web.config file. Under <AppSettings>, change the value of the search:define key to "Solr".
    <AppSettings>
       <add key="role:define" value="Stanalone"/>
       <add key="search:define" value="Solr"/>
    </AppSettings>
    
    If there is no search:define key, you may add it.
  2. Open the ConnectionStrings.config file in the inetput\wwwroot\<Sitecore Instance name>.sc\App_Config\ folder. Specify the value of the solr.search key and add the token solrCloud=true:
    <add name="solr.search" connectionString="<Solr HTTP Endpoint>;solrCloud=true"/>
    
  3. Optionally, if you use SearchStax to configure Solr Basic Authentication, you will need to add a user's credentials to the connection string as shown:
    <add name="solr.search" connectionString="https://username:password@<loadbalancer>/solr;solrCloud=true"/>
    

Populate Schema from the Control Panel

Follow these steps to populate the Solr schema:

  1. Log in to the Sitecore Content Management environment.
  2. Open the Sitecore Control Panel.
  3. In the Indexing tab, click Populate Solr Managed Schema.
  4. Select all indexes and click Populate.
Sitecore Solr SearchStax schemas

SwitchOnRebuild (Optional)

If you are interested in the Sitecore SwitchOnRebuild feature, see Can we use Sitecore's SwitchOnRebuild with SearchStax?

Questions?

Do not hesitate to contact the SearchStax Support Desk.