Introduction

Starting with ICM 7.10.16.6 the default search adapter included in the responsive starter store (component set a_responsive) changed.

This cookbook provides different recipes that describe the necessary changes to existing assemblies to use the different adapters that are provided as separate component sets. 

References

• Guide - Deployment Solr Cloud Server
• Recipe - Setup project using Solr Cloud

Recipe: Continue To Use Solr4 Adapter (valid to ICM 7.10.30.2)

Problem

An existing project uses the Solr search adapter that was included in the business component and this adapter should still be used. 

Solution

1. Add version properties to reference the Solr4 component set version.
2. Include Solr host type.
3. Include Solr cartridges from the Solr4 component set.
4. Add deploy.gradle and apply the SolrDeploymentPlugin.
5. Adapt dependencies of custom cartridges from com.intershop.business:ac_search_solr to com.intershop.solr4:ac_search_solr.

Discussion

1. Add a version properties file solr4.version to reference the used versions of the Solr4 component set and the used web archive containing the Solr4 server.

   solr4.version

   com.intershop.solr4:* = 29.0.2
   com.intershop:solr4war = 1.0.2
   

2. Reference the created version file in your build.gradle of your component set by adding the following lines to the versionRecommendation - provider section.

   build.gradle

   versionRecommendation {
       provider {		
           // solr4 + war dependencies
           properties('solr4', file('solr4.version')) {}
   ...

3. Include the Solr host type into the host type section within the build.gradle of your project assembly.

   project_assembly/build.gradle

   hostTypes {        
   
           solr {
               include (
                   'com.intershop:3rd_tomcat',
                   'com.intershop.infrastructure:runtime',
                   'com.intershop.infrastructure:tcm',
                   'com.intershop:solr4war',
               ) {
                   transitive = false
               }
   
               includeLocal = true
           }
   ...

4. Add the deployment of the Solr4 configuration to the share section by adding a line to include 'com.intershop.solr4:solr4_config' into the share deployment.

   project_assembly/build.gradle - share include

   	hostTypes {
   		share {
               include (
                   'com.intershop.solr4:solr4_config',
   ...

5. Add the cartridges of the Solr4 component set to the cartridge list of the assembly by appending the cartridges to the existing cartridge list order.

   project_assembly/build.gradle - cartridges

        cartridges {
   
           def solr4ProductionCartridges = [
               'ac_search_solr',
               'ac_search_solr_bo',
           ]
   
           include('com.intershop.solr4:ac_search_solr',
                   'com.intershop.solr4:ac_search_solr_bo',
                               in:[development, test, production])
   ...
           order = listFromAssembly('com.intershop.assembly:commerce_management_b2c') + storefrontCartridges + initCartridges + developerCartridges + testCartridges + solr4ProductionCartridges
        }

6. To deploy the Solr host type and configurations, it is necessary to add the SolrDeployment plugin to your deployment. Add a deploy.gradle to your assembly:

   project_assembly/deploy.gradle

   apply plugin: com.intershop.deploy.intershop.IntershopPlugins
   apply plugin: com.intershop.deploy.intershop.SolrDeploymentPlugin
   

7. Disable the use of the inherited deploy.gradle to use the deploy.gradle of your assembly by removing 'deploy.gradle' from the included artifacts:

   project_assembly/build.gradle

    assembly {
        inheritFrom('com.intershop.assembly:commerce_management_b2c') {
   -        includeArtifacts type:['deploy-gradle', 'deploy-settings-gradle']
   +        includeArtifacts type:['deploy-settings-gradle']
        }

8. Instead of referring to the Solr cartridge from com.intershop.business, the new component Solr4 needs to be used in the build.gradle of cartridges that extend the Solr adapter.

   cartridge/build.gradle

   //for using base classes from the adapter
       compile group: 'com.intershop.solr4', name: 'ac_search_solr'
   
   //to directly use solrj classes
       compile ("org.apache.solr:solr-solrj:4.8.1")
       {
       exclude module: 'log4j'
       exclude module: 'wstx-asl'
       }

Recipe: Use SolrCloud Adapter

Problem

The SolrCloud search adapter should be used in a project.

Solution

1. Setup a SolrCloud server.
2. Add version properties to reference the SolrCloud component set version.
3. Include SolrCloud cartridges from the SolrCloud component set.
4. Add the SolrCloud deployment plugin.

Discussion

1. To use the SolrCloud search adapter, set up and deploy a SolrCloud Server. Please follow the Guide - Deployment Solr Cloud Server.

2. Add a version property file solrcloud.version to reference the used version of the SolrCloud component set.

   solrcloud.version

   com.intershop.solrcloud:* = 2.0.3
   

3. Reference the created version file in your build.gradle of your component set by adding the property file to the versionRecommendation - provider section.

   build.gradle

   versionRecommendation {
       provider {		
           // solrcloud dependencies
           properties('solrcloud', file('solrcloud.version')) {}
   ...

4. Add the solrcloud_config to the include section of the share host type. Add the cartridges of the SolrCloud component set to the cartridge list of the assembly by appending the cartridges to the existing cartridge list order.

   project_assembly/build.gradle - cartridges

   	hostTypes {
   		share {
               include (
                   'com.intershop.solrcloud:solrcloud_config',
   
   ...
        cartridges {
   
           def solrcloudProductionCartridges = [
               'ac_solr_cloud',
               'ac_solr_cloud_bo',
           ]
   
           include('com.intershop.solrcloud:ac_solr_cloud',
                   'com.intershop.solrcloud:ac_solr_cloud_bo',
                               in:[development, test, production])
   ...
           order = listFromAssembly('com.intershop.assembly:commerce_management_b2c') + storefrontCartridges + initCartridges + developerCartridges + testCartridges + solrcloudProductionCartridges
        }

5. To configure ICM for using the SolrCloud server, it is necessary to set the zooKeeperHostList and clusterIndexPrefix properties in your environment properties. To deploy these environment properties for your ICM server, create a deploy.gradle file in your project assembly directory with the following content:

   project_assembly/deploy.gradle

   apply plugin: com.intershop.deploy.intershop.IntershopPlugins
   apply plugin: com.intershop.deploy.intershop.SolrCloudDeploymentPlugin
   
   deployment {
       if (target.includeShare) {
           filters {
               overrideProperties('solrCloudProperties') {
                   dir target.shareDirectory
                   include 'system/config/cluster/appserver.properties'
   				properties['solr.zooKeeperHostList'] = solrcloud.zooKeeperHostList
                   properties['solr.clusterIndexPrefix'] = solrcloud.clusterIndexPrefix
               }
           }
       }
   }

6. Disable the use of the inherited deploy.gradle to use the deploy.gradle of your assembly.

   project_assembly/build.gradle

    assembly {
        inheritFrom('com.intershop.assembly:commerce_management_b2c') {
   -        includeArtifacts type:['deploy-gradle', 'deploy-settings-gradle']
   +        includeArtifacts type:['deploy-settings-gradle']
        }

7. Add the SolrCloud extension to your settings.gradle:
   

   Note

   In a CaaS context, the settings.gradle is dynamically created by the Operations team. 
   However, this step is still mandatory for local development. 

   settings.gradle

   solrcloud {
   	zooKeeperHostList = 'localhost:9983'
   	clusterIndexPrefix = 'demoICMserver'
   }

   If it is an update from Solr4 to SolrCloud, remove all accesses to solr() sections.

Recipe: Continue To Use SolrCloud Adapter

Problem

In a project, the separate SolrCloud search adapter was already used and the steps from Recipe - Setup project using Solr Cloud were applied. This adapter should still be used.

Solution

1. Remove the exclusion of Solr host type.
2. Remove the exclusion of cartridges.
3. Remove the replacement of ac_search_solr cartridges with the SolrCloud cartridges.

Discussion

1. Adapt the build.gradle to remove the sections that exclude dependencies and remove the Solr host type:

   project_assembly/build.gradle

    assembly {
        inheritFrom('com.intershop.assembly:commerce_management_b2x') {
            includeArtifacts type:['deploy-settings-gradle']
   -		excludeDependencies '3rd_solr_war_int', 'ac_search_solr', 'ac_search_solr_bo', 'ac_search_solr_test', 'ac_eureka_solr'
        }
    	
    	hostTypes {
    	
   -		solr {
   -            exclude group:'com.intershop', module:'3rd_tomcat'
   -            exclude group:'com.intershop.infrastructure', module:'runtime'
   -            exclude group:'com.intershop.infrastructure', module:'tcm'
   -            exclude group:'com.intershop.business', module:'3rd_solr_war_int'
   -        }	
   
   

2. Remove the replacement of previous Solr cartridges with the SolrCloud cartridges and just add the solrcloudProductionCartridges to the cartridge list. Please also see Recipe: Use SolrCloud Adapter. 

   project_assembly/build.gradle

   -        def commerceCartridgesCartridges = listFromAssembly('com.intershop.assembly:commerce_management_b2x')
   -        def solrCloudCartridges = commerceCartridgesCartridges.plus(commerceCartridgesCartridges.indexOf('ac_search_solr'), solrCloudProductionCartridges)
   -        solrCloudCartridges = solrCloudCartridges.plus(solrCloudCartridges.indexOf('ac_search_solr_test'), solrCloudTestCartridges)
   -       
   -        order = solrCloudCartridges+ storefrontCartridges + initCartridges + developerCartridges + testCartridges
   +        order = listFromAssembly('com.intershop.assembly:commerce_management_b2c') + storefrontCartridges + initCartridges + developerCartridges + testCartridges + solrcloudProductionCartridges 
   
   

Recipe: Dependency Changes Solr Adapter Cartridge

Problem

The project used the previously included search adapter cartridges and referenced the adapter cartridge(s) in project cartridges to e.g., extend functionality of these cartridges.

Solution

In case you use a custom cartridge that extends the Solr4 Adapter the dependencies must be changed from the group business to solr4:

-    compile group: 'com.intershop.business', name: 'ac_search_solr'
+    compile group: 'com.intershop.solr4', name: 'ac_search_solr'
+    compile ("org.apache.solr:solr-solrj:4.8.1")
+    {
+      exclude module: 'log4j'
+      exclude module: 'wstx-asl'
+    }

If the custom cartridge extends the Solr Cloud Adapter, the dependencies should look like:

-    compile group: 'com.intershop.business', name: 'ac_search_solr'
+    compile group: 'com.intershop.solrcloud', name: 'ac_solr_cloud'
+    compile ("org.apache.solr:solr-solrj:8.5.1")
+    {
+       exclude module:'jcl-over-slf4j'
+    }