Taking Solr to Production

Planning Your Directory Structure

We recommend separating your live Solr files, such as logs and index files, from the files included in the Solr distribution bundle, as that makes it easier to upgrade Solr and is considered a good practice to follow as a system administrator.

/opt/solr-8.2.0
/opt/solr -> /opt/solr-8.2.0

Create the Solr User

Running Solr as root is not recommended for security reasons, and the control script start command will refuse to do so. Consequently, you should determine the username of a system user that will own all of the Solr files and the running Solr process. By default, the installation script will create the solr user, but you can override this setting using the -u option. If your organization has specific requirements for creating new user accounts, then you should create the user before running the script. The installation script will make the Solr user the owner of the /opt/solr and /var/solr directories.

You are now ready to run the installation script.

Run the Solr Installation Script

To run the script, you’ll need to download the latest Solr distribution archive and then do the following:

tar xzf solr-8.2.0.tgz solr-8.2.0/bin/install_solr_service.sh --strip-components=2

The previous command extracts the install_solr_service.sh script from the archive into the current directory. If installing on Red Hat, please make sure lsof is installed before running the Solr installation script (sudo yum install lsof). The installation script must be run as root:

sudo bash ./install_solr_service.sh solr-8.2.0.tgz

By default, the script extracts the distribution archive into /opt, configures Solr to write files into /var/solr, and runs Solr as the solr user. Consequently, the following command produces the same result as the previous command:

sudo bash ./install_solr_service.sh solr-8.2.0.tgz -i /opt -d /var/solr -u solr -s solr -p 8983

You can customize the service name, installation directories, port, and owner using options passed to the installation script. To see available options, simply do:

sudo bash ./install_solr_service.sh -help

Once the script completes, Solr will be installed as a service and running in the background on your server (on port 8983). To verify, you can do:

sudo service solr status

If you do not want to start the service immediately, pass the -n option. You can then start the service manually later, e.g., after completing the configuration setup.

We’ll cover some additional configuration settings you can make to fine-tune your Solr setup in a moment. Before moving on, let’s take a closer look at the steps performed by the installation script. This gives you a better overview and will help you understand important details about your Solr installation when reading other pages in this guide; such as when a page refers to Solr home, you’ll know exactly where that is on your system.

SOLR_PID_DIR=/var/solr
SOLR_HOME=/var/solr/data

LOG4J_PROPS=/var/solr/log4j2.xml
SOLR_LOGS_DIR=/var/solr/logs

SOLR_INSTALL_DIR=/opt/solr
SOLR_ENV=/etc/default/solr.in.sh
RUNAS=solr

service solr start

Progress Check

In the next section, we cover some additional environment settings to help you fine-tune your production setup. However, before we move on, let’s review what we’ve achieved thus far. Specifically, you should be able to control Solr using /etc/init.d/solr. Please verify the following commands work with your setup:

sudo service solr restart
sudo service solr status

The status command should give some basic information about the running Solr node that looks similar to:

Solr process PID running on port 8983
{
  "version":"5.0.0 - ubuntu - 2014-12-17 19:36:58",
  "startTime":"2014-12-19T19:25:46.853Z",
  "uptime":"0 days, 0 hours, 0 minutes, 8 seconds",
  "memory":"85.4 MB (%17.4) of 490.7 MB"}

If the status command is not successful, look for error messages in /var/solr/logs/solr.log.

Dynamic Defaults for ConcurrentMergeScheduler

The Merge Scheduler is configured in solrconfig.xml and defaults to ConcurrentMergeScheduler. This scheduler uses multiple threads to merge Lucene segments in the background.

By default, the ConcurrentMergeScheduler auto-detects whether the underlying disk drive is rotational or a SSD and sets defaults for maxThreadCount and maxMergeCount accordingly. If the disk drive is determined to be rotational then the maxThreadCount is set to 1 and maxMergeCount is set to 6. Otherwise, maxThreadCount is set to 4 or half the number of processors available to the JVM whichever is greater and maxMergeCount is set to maxThreadCount+5.

This auto-detection works only on Linux and even then it is not guaranteed to be correct. On all other platforms, the disk is assumed to be rotational. Therefore, if the auto-detection fails or is incorrect then indexing performance can suffer badly due to the wrong defaults.

The auto-detected value is exposed by the Metrics API with the key solr.node:CONTAINER.fs.coreRoot.spins. A value of true denotes that the disk is detected to be a rotational or spinning disk.

It is safer to explicitly set values for maxThreadCount and maxMergeCount in the IndexConfig section of SolrConfig.xml so that values appropriate to your hardware are used.

Alternatively, the boolean system property lucene.cms.override_spins can be set in the SOLR_OPTS variable in the include file to override the auto-detected value. Similarly, the system property lucene.cms.override_core_count can be set to the number of CPU cores to override the auto-detected processor count.

Memory and GC Settings

By default, the bin/solr script sets the maximum Java heap size to 512M (-Xmx512m), which is fine for getting started with Solr. For production, you’ll want to increase the maximum heap size based on the memory requirements of your search application; values between 10 and 20 gigabytes are not uncommon for production servers. When you need to change the memory settings for your Solr server, use the SOLR_JAVA_MEM variable in the include file, such as:

SOLR_JAVA_MEM="-Xms10g -Xmx10g"

Also, the Solr Control Script comes with a set of pre-configured Garbage First Garbage Collection settings that have shown to work well with Solr for a number of different workloads. However, these settings may not work well for your specific use of Solr. Consequently, you may need to change the GC settings, which should also be done with the GC_TUNE variable in the /etc/default/solr.in.sh include file. For more information about garbage collection settings refer to following articles: 1. https://wiki.apache.org/solr/ShawnHeisey 2. https://www.oracle.com/technetwork/articles/java/g1gc-1984535.html You can also refer to JVM Settings for tuning your memory and garbage collection settings.

Going to Production with SolrCloud

To run Solr in SolrCloud mode, you need to set the ZK_HOST variable in the include file to point to your ZooKeeper ensemble. Running the embedded ZooKeeper is not supported in production environments. For instance, if you have a ZooKeeper ensemble hosted on the following three hosts on the default client port 2181 (zk1, zk2, and zk3), then you would set:

ZK_HOST=zk1,zk2,zk3

When the ZK_HOST variable is set, Solr will launch in "cloud" mode.

ZK_HOST=zk1,zk2,zk3/solr

bin/solr zk mkroot /solr -z <ZK_node>:<ZK_PORT>

Solr Hostname

Use the SOLR_HOST variable in the include file to set the hostname of the Solr server.

SOLR_HOST=solr1.example.com

Setting the hostname of the Solr server is recommended, especially when running in SolrCloud mode, as this determines the address of the node when it registers with ZooKeeper.

Environment banner in Admin UI

To guard against accidentally doing changes to the wrong cluster, you may configure a visual indication in the Admin UI of whether you currently work with a production environment or not. To do this, edit your solr.in.sh or solr.in.cmd file with a -Dsolr.environment=prod setting, or set the cluster property named environment. To specify label and/or color, use a comma delimited format as below. The + character can be used instead of space to avoid quoting. Colors may be valid CSS colors or numeric e.g. #ff0000 for bright red. Examples of valid environment configs:

Override Settings in solrconfig.xml

Solr allows configuration properties to be overridden using Java system properties passed at startup using the -Dproperty=value syntax. For instance, in solrconfig.xml, the default auto soft commit settings are set to:

<autoSoftCommit>
  <maxTime>${solr.autoSoftCommit.maxTime:-1}</maxTime>
</autoSoftCommit>

In general, whenever you see a property in a Solr configuration file that uses the ${solr.PROPERTY:DEFAULT_VALUE} syntax, then you know it can be overridden using a Java system property. For instance, to set the maxTime for soft-commits to be 10 seconds, then you can start Solr with -Dsolr.autoSoftCommit.maxTime=10000, such as:

bin/solr start -Dsolr.autoSoftCommit.maxTime=10000

The bin/solr script simply passes options starting with -D on to the JVM during startup. For running in production, we recommend setting these properties in the SOLR_OPTS variable defined in the include file. Keeping with our soft-commit example, in /etc/default/solr.in.sh, you would do:

SOLR_OPTS="$SOLR_OPTS -Dsolr.autoSoftCommit.maxTime=10000"

File Handles and Processes (ulimit settings)

Two common settings that result in errors on *nix systems are file handles and user processes.

It is common for the default limits for number of processes and file handles to default to values that are too low for a large Solr installation. The required number of each of these will increase based on a combination of the number of replicas hosted per node and the number of segments in the index for each replica.

The usual recommendation is to make processes and file handles at least 65,000 each, unlimited if possible. On most *nix systems, this command will show the currently-defined limits:

ulimit -a

It is strongly recommended that file handle and process limits be permanently raised as above. The exact form of the command will vary per operating system, and some systems require editing configuration files and restarting your server. Consult your system administrators for guidance in your particular environment.