Walkthrough: Setting up Solr

Last updated Monday, November 27, 2017 in Sitecore Experience Platform for Administrator, Developer
Keywords: Search

This walkthrough describes how to set up Solr for use with Sitecore. It does not cover all configuration options available in Solr: it only documents configuration details specific for using Solr in Sitecore.

This walkthrough describes how to:

Install Solr

Follow the instructions in the Solr documentation to install Solr. The Solr website lists resources. The wiki hosted there is especially useful. Check the Sitecore Solr compatibly table as well.

Notes

You must you use a separate core for each index. This topic on the Solr wiki introduces the multiple core concept.

When you configure Solr, use the 64-bit version of the Java Virtual Machine (JVM) for production servers. Solr allocates 512 MB of memory by default. If you require Solr to have access to more memory you can adjust these limits when Solr starts up. See the official Solr documentation for more information.

Generate an XML Schema for Solr

Solr needs a defined xml schema when working with documents.

You can modify an existing schema with the Generate the Solr Schema.xml file tool. This tool automatically generates a basic schema and ensures all the fields that Sitecore needs are present. You can add your own fields to this schema, as long as you do not change the system index fields.

Note

The Identity account of the Application Pool of the Sitecore instance must have access to both the source and the target file locations.

To generate a new Solr schema.xml file:

  1. In the Control Panel, click Generate the Solr Schema.xml file:

    Picture 3

  2. In the Source file field, enter the path to the Solr schema that you want to use.
  3. In the Target file field, enter the destination for the new schema file, for example, the website root folder: C:\inetpub\wwwroot\<sitename>\Website\schema.xml:

    Picture 9

  4. Click Generate. Sitecore updates the schema.xml file and adds all the necessary fields that it needs.
  5. Copy the file to the conf folder of the relevant core.

Note

If you have any other field definitions, copy fields, or dynamic fields configured in your schema, they are overwritten by the schema generator. To preserve these fields, copy your original schema and merge it with the newly generated schema afterwards.

Enable Solr term support

Note

Solr term is not used and supported in Sitecore 8.1 Update-1 and later, and you do not need to enable it. Sitecore uses Solr faceting instead.

When you implement Solr for use with Sitecore, you must enable term support in the Solr search handler.

The term functionality is built into Solr but is disabled by default. To power the dropdowns in the UI, you must enable the terms component.

To enable Solr term support:

  1. Open the solrconfig.xml and locate this node: <requestHandler name="/select" class="solr.SearchHandler">
  2. Change the node to this:
    <requestHandler name="/select" class="org.apache.solr.handler.component.SearchHandler">
        <lst name="defaults">
          <bool name="terms">true</bool>
          <str name="echoParams">explicit</str>
          <int name="rows">10</int>
          <str name="df">text</str>
        </lst>
        <arr name="last-components">
          <str>terms</str>
        </arr>
      </requestHandler>
  3. Save your changes. Repeat for each core.

Verify that Solr is running correctly

After generating a new schema.xml file and updating the solrconfig.xml file, you must verify that Solr runs correctly.

To verify that Solr is running correctly:

  1. Ensure Solr is not running. A full restart is needed so that it loads the new configuration.
  2. Start Solr.
  3. Check the output log files. If there are no errors, then open the Solr administration page.

    To open the administration page, enter the following URL in your browser: http://localhost:8983/solr/admin:

    Picture 4

  4. Click Core Admin and then click a core. In this example, there is one core, called itembuckets:

    Picture 5

If you can see the Solr administration page and do not get any errors in the log files, then Solr is running correctly.

Configure an IOC container

Download the Solr support package for your version of Sitecore from dev.sitecore.net, in Additional Tools section.

This package contains files that you must copy to the /bin folder of your installation. You can also acquire these packages via NuGet.

The following versions are currently verified, but later versions may also work:

  • Castle Windsor v3.1.0.0
  • AutoFac v2.5.2
  • Ninject v3.0.0
  • StructureMap v2.6.2
  • Unity v2.1.505

Note

These projects are open source and updated regularly. You might have to request a specific version of the container from NuGet using the – Version switch in the NuGet command line.

Select the correct support DLL files

When you choose a suitable IOC container, ensure that you include the correct support DLLs in the bin directory alongside the DLLs installed for the container.

Depending on your container, ensure that you also copy the following DLL files into the /bin folder:

IOC container

DLL files

Castle Windsor

Castle.Facilities.SolrNetIntegration.dll

Sitecore.ContentSearch.SolrProvider.CastleWindsorIntegration.dll

AutoFac

AutofacContrib.CommonServiceLocator.dll

AutofacContrib.SolrNet.dll

Sitecore.ContentSearch.SolrProvider.AutoFacIntegration.dll

Ninject

CommonServiceLocator.NinjectAdapter.dll

Ninject.Integration.SolrNet.dll

Sitecore.ContentSearch.SolrProvider.NinjectIntegration.dll

StructureMap

StructureMap.SolrNetIntegration.dll

Sitecore.ContentSearch.SolrProvider.StructureMapIntegration.dll

Unity

Unity.SolrNetIntegration.dll

Sitecore.ContentSearch.SolrProvider.UnityIntegration.dll

Configure Sitecore to work with Solr

Follow the steps in this section to configure Sitecore to work with Solr.

Note

Do not make changes directly to the configuration files. Instead, you must create a patch file that performs the required changes during runtime.

Enable the Solr Config File

Your website Include folder contains several configuration files. Lucene search is enabled by default. If you want to use Solr, you normally disable the Lucene search config files and enable the Solr config file (although it is technically possible to use Lucene for some indexes and Solr for other indexes). This enables Solr integration and gives you access to all the Solr specific configuration settings.

To switch configuration files so that Solr is enabled and Lucene is disabled:

  1. Navigate to the website Include folder: wwwroot\<sitename>\App_Config\Include\
  2. Disable the following Lucene configuration files by adding .example to the file name extension:

    Sitecore.ContentSearch.Lucene.DefaultIndexConfiguration.config

    Sitecore.ContentSearch.Lucene.Index.Analytics.config

    Sitecore.ContentSearch.Lucene.Index.Core.config

    Sitecore.ContentSearch.Lucene.Index.Master.config

    Sitecore.ContentSearch.Lucene.Index.Web.config

    Sitecore.ContentSearch.Lucene.Indexes.Sharded.Core.config.example

    Sitecore.ContentSearch.Lucene.Indexes.Sharded.Master.config.example

    Sitecore.ContentSearch.Lucene.Indexes.Sharded.Web.config.example

  3. Enable the Sitecore.ContentSearch.Solr.*.config file by removing .example from the file name.

    Sitecore.ContentSearch.Solr.DefaultIndexConfiguration.config.example

    Sitecore.ContentSearch.Solr.Index.Analytics.config.example

    Sitecore.ContentSearch.Solr.Index.Core.config.example

    Sitecore.ContentSearch.Solr.Index.Master.config.example

    Sitecore.ContentSearch.Solr.Index.Web.config.example

Solr specific settings

The following Solr specific settings can be found in the Sitecore.ContentSearch.Solr.DefaultIndexConfiguration.config file.

  • Specifying a Solr Service Address

    This setting tells Sitecore where the Solr server is located. Sitecore appends the core name so only the base address needs to be supplied.

    <setting name="ContentSearch.Solr.ServiceBaseAddress" value="http://localhost:8983/solr" />

  • Enabling a Search Provider

    This setting tells Sitecore that Solr is enabled and so attempts to connect to the Solr server the next time the index is accessed. If it cannot connect you get an error. To disable, set this back to Lucene, which was the default setting.

    <setting name="ContentSearch.Provider" value="Solr" /> (Default: “Lucene”)

  • Maximum Number of Search Results

    This is a global setting found in the Sitecore.ContentSearch.config file.

    This setting contains the maximum number of documents to retrieve on a single request if a limit has not been specified in the query, for example, Take(10). It is important to remember, for performance reasons, when querying how many results will be returned from the query being run and to handle them correctly, for example by using paging.

    <setting name="ContentSearch.SearchMaxResults" value="500" />

  • Enabling Batch Mode

    When an item is indexed the composed document is saved to the search index. When the default Lucene provider is enabled then each write is being flushed to a file on the local disk. When a document is written using the Solr provider the update has to travel over a network.

    Picture 26

    When an index is rebuilt a large number of document updates are created, this could result in a lot of network traffic which is not very efficient. Therefore using batch can help to optimize the update process as your indexes grow in size.

    <setting name="ContentSearch.Update.BatchModeEnabled" value="true" />

    <setting name="ContentSearch.Update.BatchSize" value="500" />

    Batch mode (enabled by default) takes these document updates and only flushes to the Solr server when the batch has reached a certain size.

    Picture 27

    As your index grows you may want to increase this batch size to gain the most out of this process.

Specify an IOC container

You must update the global.asax file so that the Solr provider is loaded when the application start. Do this by specifying that your application inherits from one of the application classes provided; the specific configuration is dependent on your choice of IOC container.

For example, to update the global.asax file to use Castle Windsor:

  1. In your website root folder, locate the global.asax file:

    wwwroot\<sitename>\Website

  2. Open global.asax and in the first line, replace:

    Inherits="Sitecore.Web.Application"

    With

    Inherits="Sitecore.ContentSearch.SolrProvider.CastleWindsorIntegration.WindsorApplication"

    This registers the IOC (inversion of control) components for Castle Windsor enabling Solr integration to work correctly.

Alternatively, replace the Sitecore.Web.Application reference with a reference to one of the following IOC containers:

IOC Container

Class

Castle Windsor

<%@Application Language='C#' Inherits="Sitecore.ContentSearch.SolrProvider.CastleWindsorIntegration.WindsorApplication" %>

Autofac

<%@Application Language='C#' Inherits="Sitecore.ContentSearch.SolrProvider.AutoFacIntegration.AutoFacApplication" %>

Ninject

<%@Application Language='C#' ' Inherits="Sitecore.ContentSearch.SolrProvider.NinjectIntegration.NinjectApplication" %>

StructureMap

<%@Application Language='C#' ' Inherits="Sitecore.ContentSearch.SolrProvider.StructureMapIntegration.StructureMapApplication" %>

Unity

<%@Application Language='C#' Inherits="Sitecore.ContentSearch.SolrProvider.UnityIntegration.UnityApplication" %>

Before you can start using the Solr indexing system, you must re-index Sitecore content.

To rebuild the Sitecore search indexes:

  1. In the Control Panel, and click Indexing manager.

    Picture 13

  2. Select Select all, and then click Rebuild.

    Picture 15

Send feedback about the documentation to docsite@sitecore.net.