Guide - Solr Replication

Product Version


Product To Version



1 Introduction

This document is about mass data replication (staging) of Solr search indexes for ICM staging environments. Solr indexes in general reside somewhere in a file system and reflect data that is indexed from the ICM database. There are no search index related artifacts in the database. When replicating database content with ICM mass data replication it is necessary to also transfer the index's file system content from the source system (Edit system) to target system (Live system).

This document covers Solr standalone as well as Solr cloud.

1.1 Glossary

ICMIntershop Commerce Management
coreA lucene index on Apache Solr (standalone) side
collectionA lucene index on Apache Solr side (cloud mode)
It may consist of multiple shards and replicas which in turn are cores itself.

1.2 References

For general information about data replication see: Concept - Mass Data Replication

In order to use Solr Cloud replication please mind configuration keys described in section Configuration of IS7 of the Guide - Deployment Solr Cloud Server.

2 Replication Process

2.1 Generic Search Index Replication

The search index framework provides the following common search engine neutral artifacts to help with the replication of search indexes.

Staging Group:

FND_SearchIndexes A staging group that uses the file system staging processor to transfer file system content that is located in the searchindexes folder of the shared file system.

Staging Decorator:

RefreshSearchIndexesDecorator is the standard staging decorator that is contained in cartridge bc_search. It will process indexes that are replicated within the file system and will call a reload after switching of active directories.

Data Replication Group:

SEARCH_INDEXES Data Replication Group for the Commerce Management application that directly maps to the search indexes staging group.

Properties general file in /share/system/config/cluster that contains properties specific to ICM data replication feature.

2.2 Solr Cloud Specific Replication

This chapter describes the replication as with component set f_solrcloud.

When using Solr cloud mode the index data itself is contained in a Solr cluster, completely independent from the ICM instance. In that respect it is not different to any relational database system. As a result, we need to transfer the Solr search indexes from one Solr (Edit) instance to another Solr (Live) instance. This is done using the Solr 6 backup and restore feature. Even if the ICM source (Edit) and target (Live) system share a single Solr cluster - indexes need to be backed up and restored during replication. This process is done with a dedicated staging decorator included in cartridge ac_solr_cloud.

The deployment of component set f_solrcloud changes the to use the BackupAndRestoreSolrCloudIndexesDecorator as decorator for the search index staging processor.


Before the preparation phase (onPrePreparationHook) the decorator determines all the indexes that are contained in the domains that are processed by the current staging process. For all the determined Solr indexes a backup is triggered via Solr Collection Admin API. The backups are stored to a given backup location influenced by configuration key solr.cloudBackupLocation (see Configuration of IS7).

Index backups in the backup location are stored in directories named with the following naming scheme:  <staging-process-id>-<domain>-<indexID>

In the target (Live) system at the refresh cache phase of the replication (onPreRefreshCacheHook) the indexes are restored from the backups into separate collections named: <solr.clusterIndexPrefix><domain-name>-<indexID><solr.collectionSuffix1> or solr.collectionSuffix2 respectively. There is an alias that points to the current live collection. The backup is restored to the collection suffix that is currently not referred to by the alias.

The restore of the backed up index also restores the config set but this is named like the config set of the source (Edit) index. This is perfectly normal as the backup contains the reference to the config set along with the index data. Now, since the search index framework needs a certain naming scheme for config set and index the restored config set must be changed. It is moved to a new config set that is named like the target (Live) index. And the target index is modified to use this config set.

Backup and restore operations are performed by submitting the backup or restore operation to the Solr server via asynchronous requests. Waiting to complete these operations has a separate timeout setting: solr.backupRestoreTimeout


Depicted above is a simple (development) setup with a single Solr server that is used by live and edit instances. The solr.zookeeperHostList points the ICM application servers to the same solr server instance. The solr.clusterIndexPrefix distinguishes between the collections of the edit and live instance and the solr.cloudBackupLocation points to an existing directory on the same solr server.


A single Solr server or cluster may even be shared between multiple ICM instances by setting configuration  solr.clusterIndexPrefix to a name that distinguishes them from each other. It defaults to a simple host name followed by the instance ID of the ICM installation.

The next picture shows a setup that uses a single Solr server for the editing system and a Solr cloud cluster for the live system. The backup directory is shared by a network file system between the edit and all the live servers.



All Solr server in the Solr cluster(s) for source (Edit) and target (Live) system need a common shared file system where the backups are stored, written by an arbitrary Solr server of the Solr cluster for source (Edit) system and read by an arbitrary Solr server of the Solr cluster for target (Live) system. This shared file system has nothing to do with the IS7 shared file system, instead it is for the Solr servers only.

The solr.replicationFactor on the live system is set to the number of available live Solr server nodes. (default is =1, maximum is the number of running Solr server nodes). This property is used at restoring the collection to the live system to distribute replicas of the index to ensure load balancing and availability even if one of the Solr servers goes down. The ICM application servers connect to the zookeeper ensemble by the given solr.zooKeeperHostList that lists the zookeepers managing the available Solr servers.


Take care that the backup directory does not run out of space. The backup directory is currently not cleaned up automatically. A system administrator must manually delete backups from old replication processes.

 If the Solr backup directory is also shared to the application servers and is accessible at the same location (solr.cloudBackupLocation), the data replication process will do additional checks to verify the successful execution of the backup ( ISSEA-123 - Getting issue details... STATUS SolrCloud Adapter Version 2.1.0 and higher)

Known Limitations:

  • Undo of the search index replication is only supported with Solr Cloud Adapter version 2.1.0 and higher( ISSEA-121 - Getting issue details... STATUS ).
    Workaround for previous versions: Use the old indexes by switching back the aliases manually as Solr admin (http://localhost:8983/solr/admin/collections?action=CREATEALIAS&name=<indexalias>&collections=<physicalcollectionname>)
  • Deleting indexes on the editing system and data replication does not delete the collections on the live system.
    Workaround: Delete manually as Solr admin (http://localhost:8983/solr/admin/collections?action=DELETE&name=<physicalcollectionname>) and Solr zookeeper client script (solr/bin/solr zk rm -r /configs/<collection name>)

2.3 Solr Search Index Replication (ac_search_solr - Solr 4.8)

This section describes the replication as with cartridge ac_search_solr component set f_search_solr.

All the data and configuration of a Solr search index is entirely contained in the shared file system of the ICM. Multiple Solr instances use the same index data files from the shared file system.

The search index replication uses the generic search index file system staging process to transfer these files from the edit to the live system.

After switching the active directory at the end of the replication the Solr search indexes need to be refreshed (reloaded). This is done with the help of the RefreshSearchIndexes decorator. This decorator determines all indexes of currently replicated domains and sends a SearchIndexReload event to each application server in the ICM cluster. The event processing will then do a call to the reload-method of each index. The one application server that sends out the event will process the event a bit different. It will pass a cluster=true parameter to the reload method. This cluster=true reload creates a new core (<core>-offline) with the new (inactive) data directory and swaps the current online core with this newly created core. After swapping the old core is deleted. These commands are send to each of the Solr server nodes that are listed in the solr.SolrClusterNodeURLs property. This will load the new index data into each separate Solr server.


The picture above shows the properties and the location of data in that variant of Solr index replication.  If separate Solr servers are used the solr.SolrServerURL directs the search requests to an additional load balancer that distributes these requests to the Solr servers. During indexing the first Solr server in the list of the solr.SolrClusterNodeURLs receives the indexing requests.


The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets