Solr Replication Guide

Manual Opensolr Index Replication

Overview

Opensolr supports manual index-to-index replication using Solr's built-in replication handler. This lets you replicate data from a Leader index to one or more Follower indexes — across different Opensolr clusters or even across continents — over HTTPS with HTTP Basic Authentication.

How It Works

Solr replication uses a pull model: the Follower periodically polls the Leader for changes. When the Leader has new data (after a commit or startup), the Follower downloads the updated index segments.

LEADER
Serves index data


FOLLOWER
Pulls index updates

Step 1: Leader Configuration

On your Leader index, add the following to solrconfig.xml (via the Opensolr Config Editor):

<requestHandler name="/replication" class="solr.ReplicationHandler">
    <lst name="master">
        <str name="replicateAfter">startup</str>
        <str name="replicateAfter">commit</str>
        <str name="confFiles">schema.xml,stopwords.txt,elevate.xml</str>
        <str name="maxNumberOfBackups">0</str>
    </lst>
</requestHandler>

Configuration notes

replicateAfter — triggers replication after startup and/or commit
confFiles — config files to replicate alongside the index data
maxNumberOfBackups — set to 0 to disable backup snapshots on the leader

Step 2: Follower Configuration

On your Follower index, add this to solrconfig.xml:

<requestHandler name="/replication" class="solr.ReplicationHandler">
    <lst name="slave">
        <str name="masterUrl">https://SRV.OPENSOLR.COM/solr/YOUR_LEADER_INDEX_NAME</str>
        <str name="pollInterval">00:00:05</str>
        <str name="httpBasicAuthUser">YOUR_AUTH_USER</str>
        <str name="httpBasicAuthPassword">YOUR_AUTH_PASSWORD</str>
    </lst>
</requestHandler>

Important

masterUrl — the full HTTPS URL to your leader index (as shown in the Opensolr dashboard)
pollInterval — how often the follower checks for changes (format: HH:MM:SS)
httpBasicAuthUser / httpBasicAuthPassword — the HTTP auth credentials for your leader index

Step 3: Network Access (IP Whitelisting)

Both indexes need to be able to reach each other over the network. In the Opensolr dashboard, grant replication access by IP:

On the Leader

Allow the Follower server's IP to access /replication. Find it with: ping FOLLOWER_HOSTNAME

On the Follower

Allow the Leader server's IP to access /replication. Find it with: ping LEADER_HOSTNAME

Both leader and follower must have identical schema.xml files. Any mismatch will cause replication to fail or produce inconsistent results.

Example: Basic Leader-Follower Setup

Suppose you have two Opensolr indexes:

Role	Index Name	Cluster
Leader	`products`	`fr.opensolr.com`
Follower	`products_replica`	`uk2.opensolr.com`

Add the Leader XML config to products at fr.opensolr.com
Add the Follower XML config to products_replica at uk2.opensolr.com, with masterUrl pointing to https://fr.opensolr.com/solr/products
Run ping fr.opensolr.com and ping uk2.opensolr.com to get their IPs
Whitelist those IPs in each index's Opensolr dashboard
Save configs and reload both indexes — replication will begin automatically

Advanced: Setting Up a Repeater

A Repeater is an index that acts as both a Follower (pulling from a Leader) and a Leader (serving data to other Followers). This is useful when:

You want to reduce load on the primary Leader by having a middle tier
You need to replicate across regions without every Follower hitting the same Leader
You want a cascading replication topology for large-scale deployments

LEADER
Primary source


REPEATER
Pulls & serves


FOLLOWERS
End replicas

Repeater Configuration

The repeater's solrconfig.xml combines both the slave and master blocks in a single replication handler:

<requestHandler name="/replication" class="solr.ReplicationHandler">
    <!-- Pull from the primary Leader -->
    <lst name="slave">
        <str name="masterUrl">https://LEADER_SRV.OPENSOLR.COM/solr/LEADER_INDEX</str>
        <str name="pollInterval">00:00:10</str>
        <str name="httpBasicAuthUser">YOUR_AUTH_USER</str>
        <str name="httpBasicAuthPassword">YOUR_AUTH_PASSWORD</str>
    </lst>
    <!-- Serve to downstream Followers -->
    <lst name="master">
        <str name="replicateAfter">startup</str>
        <str name="replicateAfter">commit</str>
        <str name="confFiles">schema.xml,stopwords.txt,elevate.xml</str>
        <str name="maxNumberOfBackups">0</str>
    </lst>
</requestHandler>

Then, each downstream Follower points its masterUrl to the Repeater instead of the primary Leader:

<requestHandler name="/replication" class="solr.ReplicationHandler">
    <lst name="slave">
        <str name="masterUrl">https://REPEATER_SRV.OPENSOLR.COM/solr/REPEATER_INDEX</str>
        <str name="pollInterval">00:00:05</str>
        <str name="httpBasicAuthUser">REPEATER_AUTH_USER</str>
        <str name="httpBasicAuthPassword">REPEATER_AUTH_PASSWORD</str>
    </lst>
</requestHandler>

Repeater considerations

The repeater must have the same schema.xml as both the leader and the downstream followers
IP whitelisting is needed at every link in the chain: Leader must allow the Repeater, and the Repeater must allow its Followers
The repeater's pollInterval should be slightly longer than the downstream followers' to avoid replication conflicts
You can chain multiple repeaters for complex topologies, but keep it simple — each additional hop adds replication latency

Example: Three-Tier Replication

Role	Index	Cluster	Pulls from
Leader	`catalog`	`de.opensolr.com`	—
Repeater	`catalog_eu`	`fr.opensolr.com`	`de.opensolr.com`
Follower	`catalog_uk`	`uk2.opensolr.com`	`fr.opensolr.com`
Follower	`catalog_us`	`us.opensolr.com`	`fr.opensolr.com`

In this setup, catalog_eu pulls from the primary leader in Germany and serves as a leader for the UK and US replicas. The primary leader only handles one replication connection instead of three.

Questions?

Need help setting up replication for your Opensolr indexes? Reach out to us at the Opensolr Contact Page — we're happy to help you design the right replication topology for your use case.

Read Full Answer