Saturday, February 28, 2015

Sitecore 8 + Solr (part 3/3): Configur-ageddon

So far in this series we have installed Tomcat and Solr. Hopefully it has been a relatively easy process. Unfortunately, I can't promise today's post will be as easy. I've tried to balance making the configuration process as pain-free as possible, while not shielding anyone from the details that tripped me up. My goal is to take (all?) the guesswork out of this process. Let me know how I did!

[N.B.: As I was finishing up this final post I saw that update 2 for Sitecore was released. A quick perusal of the release notes leaves me feeling fairly confident that these instructions -- created with Sitecore 8 update 1 in mind -- should still be valid for update 2. No doubt I will soon need to upgrade my Sitecore environments to update 2 in the near future. Rest assured any issue(s) I encounter I will document here.]

Update (3-3-2015, 3-8-2015): As promised, I have updated this guide to comply with Sitecore 8 update 2. This means that if you want to upgrade from update 1, then you will need to create a couple of new cores and delete an old one (see step 6) and replace a DLL (see step 9). If you are starting fresh from update 2, then don't worry about any of this and dive right in!

  1. Stop the Tomcat service.
  2. Go to the root of your Solr instance, in my case, D:\solr. We need to modify the "collection1" directory to serve as one of the cores (folders with config files and index data) required by Sitecore.
    1. Rename the folder to "sitecore_analytics_index"
    2. Inside the folder you will find a file called “” which you may edit with a text editor. You need to change the “name” value to the name of your core. For example, when I create the “sitecore_analytics_index” core, then I will edit the “” file to have the value name=sitecore_analytics_index

  3. Start the Tomcat service and visit the Solr administration page. You may need to reload your browser page if it was already up. Click on the “Core Admin” menu item. If you modified the old “collection1” core correctly you should now see a sitecore_analytics_index core.

  4. Stop the Tomcat service. Now we need to fix the schema of our “sitecore_analytics_index” core, otherwise Sitecore cannot parse the xml correctly. Edit the file at \sitecore_analytics_index\conf\schema.xml according to Sitecore’s knowledge base article: Don’t forget to define the field type for pint since we are using a version of Solr later than 4.9! Start Tomcat and reload the Core Admin page.
  5. Next we must generate a new, Sitecore-specific schema. Sitecore provides a tool for this. Navigate to the Control Panel of your Sitecore instance. Look for the “Generate the Solr Schema.xml file” link and click it. Provide a path for the source and target files (they can’t be the same file.) Once you have generated your new schema, replace the old schema with it. Restart the Tomcat service and make sure the core loads correctly.
  6. A vanilla install of Sitecore 8 update 2 requires 13 cores to work correctly. So far we have one, but don’t despair, now that we have a generated a schema this process is much easier.  Essentially, we are going to use our sitecore_analytics_index core as a template to create the others. To do this:
    1. Copy the sitecore_analytics_index folder.
    2. Repeat steps 2a and 2b for each copy.
    3. When you are done, your Solr home folder should contain the following cores

    4. If you have done everything correctly you should be able to restart Tomcat and see all the cores listed above on the Core Admin page.
  7. Update (3-7-2015): I decided to create a PowerShell shortcut for this step. Save yourself time!

    Still with me? Hang in there, we are halfway home! Next, we must tell Sitecore to start using Solr instead of Lucene. This is done by appending or removing “disabled” as an extension of a configuration file’s name.
    1. Config files to DISABLE:

      \App_Config\Include\Sitecore.ContentSearch.Lucene.Indexes.Sharded.Core.config.example (left as is)
      \App_Config\Include\Sitecore.ContentSearch.Lucene.Indexes.Sharded.Master.config.example (left as is)
      \App_Config\Include\Sitecore.ContentSearch.Lucene.Indexes.Sharded.Web.config.example (left as is)

    2. Config files to ENABLE:


  8. So I know that last step was pretty tedious, but if you've made it this far then the rest will be easier. Download the Solr Support Package from Sitecore and extract the contents of the zip file.
  9. Copy the following DLLs from the Solr Support Package into the \bin folder of your Sitecore Instance [N.B.: Castle Windsor is my Inversion of Control preference as Glass also uses it. Aside from Castle Windsor, Sitecore supports AutoFac, Ninject, StructureMap, and Unity.]:

    • Castle.Facilities.SolrNetIntegration.dll
    • Microsoft.Practices.ServiceLocation.dll
    • Sitecore.ContentSearch.Linq.Solr.dll
    • Sitecore.ContentSearch.SolrProvider.CastleWindsorIntegration.dll
    • Sitecore.ContentSearch.SolrProvider.dll
    • SolrNet.dll

      Update (3-3-2015): If you are upgrading from Sitecore 8 update 1, then you only need to replace Sitecore.ContentSearch.SolrProvider.XXXXXIntegration.dll with the latest version from the Solr Support Package. All other DLLs remain unchanged.

  10. Download the Nuget package for Castle Windsor. Unzip the package by renaming the extension from .nupkg to .zip and extracting its contents. Copy the Castle.Windsor.dll from \lib\net40-client to the \bin folder of your Sitecore instance.
  11. Repeat step 10 for the Castle.Core Nuget package. Copy the Castle.Core.dll from \lib\net40-client to the \bin folder of your Sitecore instance.
  12. Since we are going to use IoC, we need to make our Sitecore instance aware of it by replacing the Application directive in the global.asax file with the following:

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

  13. In order for Sitecore to talk to Solr, we need to give it a URL. This setting is maintained in the Sitecore.ContentSearch.Solr.DefaultIndexConfiguration.config file (remember, your address may differ from mine):

    <setting name="ContentSearch.Solr.ServiceBaseAddress" value="http://tomcat:8080/solr" />

  14. SOOO CLOSE! At this point, you are ready to test how badly you have broken your Sitecore instance! With any luck, when you browse to your Sitecore site you won't encounter any yellow screens of death. If you see a YSOD complaining about "Connection error to search provider [Solr] : Unable to connect to [http://tomcat:8080/solr]" then you are likely either missing a core or made typo when creating one. Assuming you are error free, the final step is to re-index. Go to the Control Panel and look for the "Indexing manager" link. Select all indexes and click the "Rebuild" button.
  15. Drink a beer; you deserve it!

Friday, February 27, 2015

Sitecore 8 + Solr (part 2/3): Install Solr

In part one of this series, I covered the installation of Tomcat. Now we are ready to get an instance of Solr up and running.

  1. Download Solr 4.10.3 from Since we are installing on a Windows machine, you will want to get the .zip file version of the download.
  2. Extract the contents of the .zip to a temporary location of your choice.
  3. Find the \dist folder in the extracted solr-4.10.3 directory. Rename the solr-4.10.3.war to solr.war and copy the file to the Tomcat’s \webapps folder. The path in my environment was C:\Program Files\Apache Software Foundation\Tomcat 8.0\webapps.
  4. Create an empty Solr home folder. This will be the permanent place of residence on your machine for your Solr instance. For example, D:\solr is where I put my Solr instance.
  5. Find the \example\solr folder in the extracted solr-4.10.3 directory. Copy the contents of \example\solr to the empty Solr home folder you just created in step 4.
  6. Find the \example\lib\ext folder in the extracted solr-4.10.3 directory. Copy the contents of \example\lib\ext to Tomcat’s \lib folder. The path in my environment was C:\Program Files\Apache Software Foundation\Tomcat 8.0\lib.
  7. Set the home directory for Solr in Tomcat. This is done by adding a new Java option with the Monitor Tomcat program. In my case, the option was -Dsolr.solr.home=D:\solr

  8. Stop/start Tomcat and try browsing to your Solr instance. For example, http://tomcat:8080/solr.

In the third and final post of this series I'll show you how to get Sitecore and your shiny, new Solr instance working together.

Thursday, February 26, 2015

Sitecore 8 + Solr (part 1/3): Install Tomcat

This is part one of a three-part series intended to guide you step-by-step through the process of making Sitecore 8 and Solr work together. There are some good resources on the Internet, but none of them are a soup-to-nuts walkthrough, and unfortunately there are many pitfalls along the way especially if you are unfamiliar with tools like Apache Tomcat or Solr -- even if you are, the current state of Sitecore's documentation for working with Solr isn't complete for Sitecore 8. I'm sure that will change soon! :)

So, in this first post our goal is to get Apache Tomcat running on a Windows machine installed as a Windows service. Onwards!

  1. Since Solr and Tomcat both require the Java Runtime Environment (JRE) to run, we'll need to start with installing the correct JRE for our machine. This guide uses jre-8u31-windows-x64.exe.
  2. Download and install the Windows Service Installer for Tomcat. This guide uses version 8.0.18 of Tomcat, but you can safely use a more recent version. There are a few decisions to make with the installation wizard. You may choose to install the Host Manager component; this will expose a host manager gui to Tomcat’s built-in administration page.

  3. The default port used by Tomcat is 8080 (used to be 8983) but you may elect to use some other port. Don’t choose port 80 unless you are prepared to tinker with IIS to re-route requests meant for Tomcat to Tomcat; it’s not really worth the effort. Nevertheless, here is a link to a helpful resource:

    If you do not supply an optional user name and password, then you will need to manually edit the conf/tomcat-users.xml file (found under the Tomcat install path) in order to manage Tomcat from the built-in administrative web site. If you do find yourself editing the tomcat-users.xml file, don’t forget to stop-restart Tomcat for those changes to take effect. You can do this with the Monitor Tomcat tool:

  4. Test the Tomcat installation by pointing your browser to http://localhost:8080 assuming that you used port 8080 as your HTTP Connector Port.

  5. By default, the Tomcat Windows service startup type is “Manual.” This means that after rebooting your machine you will need to remember to manually restart the Tomcat service. Change the Tomcat Windows Service startup to “Automatic.”

  6. As a final, optional step, you might elect to add an alias to Tomcat so that the website can be accessed using something other than localhost. For example, you could add the tag <Alias>tomcat</Alias> to the conf/server.xml file. Don't forget—if you use an alias then make sure you either update your DNS server to use that alias or edit your hosts file in Windows. :)

At this point you should have a working Tomcat installation that will be available even after a reboot of your machine. In the next post of this series we will tackle installing Solr on top of Tomcat.

Sunday, February 1, 2015

MongoDB University Course for .NET Developers

Given that MongoDB is an integral part of Sitecore's xDB architecture starting with Sitecore 7.5, it stands to reason that our clients and colleagues will look to us, the Sitecore experts, for guidance. So what can us mere mortals who aren't already NoSQL experts do to prepare ourselves? Enroll in a course taught by NoSQL experts, of course!

Now, I know what you might be thinking, "Online courses are of limited value." And, normally, I'm right there with you. The quality of the material on offer from MongoDB University is truly worth the investment of your time, however. The only catch was none of the courses on offer were tailored for .NET developers. Last year I decided to dive in anyway with the Node.js course -- it's excellent, of course -- but just recently MongoDB University has expanded their course catalog with something for us .NET folks! Be prepared to devote several hours a week, and in return you will get a solid foundation on which to build solutions ranging from CRUD, to schema design, to performance tuning and application engineering.

Solr 4.8 and Higher with Sitecore - Schema Issue Resolved

Dan Solovay has a great blog post that details how to setup Solr with Sitecore 7. One potential problem stood out though: Sitecore didn't play well with Solr 4.8.x or higher due to an assumption Sitecore made about Solr's schema.

If you, like me, read this and had reason to hesitate then I say worry not! Sitecore has provided a solution that will allow you to deploy Solr 4.8 and later to your environment. In a nutshell, the fix is to modify the Solr's schema.xml file.

From the kb article:

  1. Make the following changes in the default schema.xml file shipped with Solr:
    • enclose all <field> and <dynamicField> elements in the <fields> tag.
    • enclose all <fieldType> elements in the <types> tag.
  2. Pass the modified schema.xml file to the Build Solr Schema Wizard to add the Sitecore specific specific configuration.
  3. Put the resulting file to the configuration folder of the Solr core.
  4. If you use Solr 4.9 or later, ensure that the following field type is defined in the schema.xml file:
  5. <fieldType name="pint" class="solr.IntField"/>
  6. Reload the core to apply schema changes.