Walkthrough: Setting up Solr

Current version: 8.2

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. 

Note

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 a 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:

  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:

  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.

Note

Sitecore 8.2, Update 6 and later versions of Sitecore 8.2 support later version of Solr. The procedure changes slightly in these versions:

The screenshot in step 3 will look like this:

Add these steps:

  1. Open the solrconfig.xml file, and add a schemaFactorynode under the config node:  <schemaFactory class="ClassicIndexSchemaFactory" />.

  2. Remove the managed-schema file from your conf folder.

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:

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

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

Note

In Sitecore 8.2, Update 1, and later you do not have to install an IOC container. Sitecore already has a default Solr provider. The following information is only applicable if you need to use another implementation.

The Sitecore Solr provider uses an IOC (Inversion of Control) container so that all the elements inside it can be swapped without re-compilation. The default Sitecore installation includes a default implementation of the Solr connector (SolrNet.dll).

If you need to use another IOC, download the Solr support package for your version of Sitecore:

  • For Sitecore 8.2 Initial Release, download from dev.sitecore.net (in the Additional tools section).

  • For Sitecore 8.2 Update-1 and later, download from the Sitecore/Solr.SupportPackage repository on GitHub.

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

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

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

  3. Enable the Sitecore.ContentSearch.Solr.*.config files 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.

  • 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.

    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.

    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

ClassClass

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" %>

Rebuild the search Indexes

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, click Indexing manager.

  2. Select Select all, and then click Rebuild.

Do you have some feedback for us?

If you have suggestions for improving this article,