Documentation Home
Changelog

SolrCloud Setup

Assuming you have Zookeeper installed and started, you can install and configure Solr. For additional information on SolrCloud setup, see the SolrCloud documentation.

This documentation assumes you are using Solr 7.7.2 and that you will run two instances of Solr on the same server. For production installations, you will want to run Solr on separate physical servers. Download Solr here and unzip it to the local file system. We'll call this location SOLR_HOME. To simplify things and get to lean setup procedure, follow these steps:

Create a directory to hold the configuration files
  • Create an empty directory on the file system wherever you like called blcSolrConfig (e.g. $SOLR_HOME/blcSolrConfig)
Copy the configuration files to the blcSolrConfig directory

For deployments using 5.2.x and higher, the Starter project has default solr configuration files that can be used:

  • From your project solr/standalone/solrhome directory, copy over the configsets and all child directories/files into the blcSolrConfig directory. So you should have:
$SOLR_HOME/blcSolrConfig
  /configsets/catalog
  /configsets/order (if you have the OMS module)
  ...

For deployments prior to 5.2.x, you will likely need to pull together the required files from solr and your project. Solr provides a number of examples and features out of the box so we will use some of their files as a starting point. Note that these steps only assume you are setting up the Catalog configuration:

  • Under the blcSolrConfig directory create the directories configsets/catalog
  • From $SOLR_HOME/server/solr, copy solr.xml to blcSolrConfig/configsets/catalog
  • From $SOLR_HOME/example/files/conf, copy solrconfig.xml and elevate.xml to blcSolrConfig/configsets/catalog
  • From the Broadleaf Demo Site distribution, copy ``site/src/main/resources/schema.xml to blcSolrConfig/configsets/catalog
Upload the configuration files to Zookeeper

Now you are ready to let Zookeeper know about Solr's configuration files using a Solr utility for Zookeeper. Make sure Zookeeper is running and execute the following command from the command line: 

./$SOLR_HOME/server/scripts/cloud-scripts/zkcli.sh -zkhost localhost:2181 -cmd upconfig -confname blc -confdir /path/to/blcSolrConfig/configsets

The above command uploads the contents of the blcSolrConfig/configsets directory to the Zookeeper Quorum using a configuration name of "blc" (more on this later). Note that other possible configsets could include order, customer, and fulfillment_order if you are using the OMS module.

Now, Zookeeper has the collection configuration files that Solr will need

Create directories to hold the Solr Server data
  • Create a directory called blcSolrServer0 anywhere on the file system (e.g. $SOLR_HOME/myServer/blcSolrServer0)
  • Copy the solr.xml file from blcSolrConfig to blcSolrServer0
  • Create a directory called blcSolrServer1 anywhere on the file system (e.g. $SOLR_HOME/myServer/blcSolrServer1)
  • Copy the solr.xml file from blcSolrConfig to blcSolrServer1
Start the Solr instances
  • Start an instance of Solr on port 8983 connecting to the Zookeeper Quorum and using blcSolrServer0 as the home directory: 
./$SOLR_HOME/bin/solr start -cloud -p 8983 -s /path/to/blcSolrServer0 -z localhost:2181,localhost:2182,localhost:2183
  • Start an instance of Solr on port 8984 connecting to the Zookeeper Quorum and using blcSolrHome1 as the home directory: 
./$SOLR_HOME/bin/solr start -cloud -p 8984 -s /path/to/blcSolrServer1 -z localhost:2181,localhost:2182,localhost:2183

Now you have 2 nodes or instances of SolrCloud running, with a 3-node Quorum (cluster) of Zookeeper instances managing the Solr cluster

Note that each of the Zookeeper instances can be configured on a different physical machine, as can each of the SolrCloud instances. The configuration name "blc" is used, when creating collections, to specify the configuration for the collection. See the collection API for more information on creating collections. Typically, Broadleaf will evaluate your cluster state and create the necessary collections and aliases for you but with SolrCloud, it is better to create the collections and aliases in advance so you can define the replication setup as well.

Create the collections

From your browser, you can hit the Solr admin endpoints to create the collections based on the configuration files we uploaded to ZooKeeper on the previous steps.

Here are example commands for creating the catalog collections, as well as the appropriate aliases (see the collection API).

http://solr_server:8983/solr/admin/collections?action=CREATE&name=catalog0&collection.configName=blc/catalog/conf&numShards=1&replicationFactor=2
http://solr_server:8983/solr/admin/collections?action=CREATE&name=catalog1&collection.configName=blc/catalog/conf&numShards=1&replicationFactor=2

http://solr_server:8983/solr/admin/collections?action=CREATEALIAS&name=catalog&collections=catalog0
http://solr_server:8983/solr/admin/collections?action=CREATEALIAS&name=catalog-reindex&collections=catalog1

We created a catalog0 and a catalog1 collection. We also created two aliases as a reference point for the Broadleaf application - catalog and catalog_reindex. Notice that as part of the collection creation, we are also specifying the replicationFactor and maxShards. This will setup shard replication so that your indexes are reduncant across different nodes (see shards and indexing). This provides failover should a node be lost. For most implementations, numShards=1 should be used. This will replication the full collection and not shard it. Sharding makes the configuration more complex and is typically not needed for most catalog sizes.

With the collections and aliases created, this is a good time to talk about how they are used.

SolrCloud allows you to create one or more collections. A collection is an abstraction on top of a Solr core. It is like a core, except that it can be distributed across multiple Solr servers. A collection can be aliased, meaning it can be assigned and referenced by another name. Each alias is assigned to exactly 1 collection. The name of the aliases is important. The name of the collections are not.

Notice, that you are only creating the collections and aliases on a single Solr node, but you will be able access the collections via their aliases on both nodes:

http://localhost:8983/solr/catalog/select?q=*

http://localhost:8983/solr/atalog_reindex/select?q=*

http://localhost:8984/solr/catalog/select?q=*

http://localhost:8984/solr/catalog_reindex/select?q=*

Notes for deployment on Windows

The above instructions are generally portable to Windows. However, there are a few things to note:

  • You should use corresponding *.cmd or *.bat instead of *.sh files
  • When uploading the the configuration to Zookeeper, on Windows, use the following:
%SOLR_HOME%\server\scripts\cloud-scripts\zkcli.bat -zkhost localhost:2181 -cmd upconfig -confname blc -confdir "C:\path\to\blcSolrConfig/configsets"
  • When starting the first instance of Solr on a Windows machine, use the following:
%SOLR_HOME%\bin\solr.cmd start -p 8983 -s "C:\path\to\blcSolrServer0" -z "localhost:2181,localhost:2182,localhost:2183"
  • And to start the second instance of Solr (on the same Windows machine) use the following:
%SOLR_HOME%\bin\solr.cmd start -p 8984 -s "C:\path\to\blcSolrServer1" -z "localhost:2181,localhost:2182,localhost:2183"