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 theconfigsets
and all child directories/files into theblcSolrConfig
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 directoriesconfigsets/catalog
- From
$SOLR_HOME/server/solr
, copysolr.xml
toblcSolrConfig/configsets/catalog
- From
$SOLR_HOME/example/files/conf
, copysolrconfig.xml
andelevate.xml
toblcSolrConfig/configsets/catalog
- From the Broadleaf Demo Site distribution, copy ``
site/src/main/resources/schema.xml
toblcSolrConfig/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 fromblcSolrConfig
toblcSolrServer0
- Create a directory called
blcSolrServer1
anywhere on the file system (e.g.$SOLR_HOME/myServer/blcSolrServer1
) - Copy the
solr.xml
file fromblcSolrConfig
toblcSolrServer1
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"