Deployment & upgrades

This section documents the current Solr line (10.0; 9.10.x the maintained 9.x branch), written and verified against the Apache Solr Reference Guide. No specific patch version is pinned. Some capabilities (the Solr Operator on Kubernetes, the package-manager ecosystem, Learning To Rank model training, and expert plugin development) are linked, not documented in depth.

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

This section’s bibliography lists the reference material consulted while preparing these pages.

Everything in What Apache Solr is & how to run it and Collections API, configsets & replica placement is enough to run Solr; this page is what changes once that cluster has to stay up. It covers turning a downloaded archive into a supervised service, the two common container/orchestration paths (Docker, and the Solr Operator on Kubernetes), backing up and restoring collections through the Collections API, restarting a cluster node by node without downtime, the shape of a version upgrade, and the package manager for installing plugins without a restart.

Taking a node to production

bin/solr start is fine for a laptop; a production node needs to survive reboots, run under its own user, and have its heap, file-descriptor limit and JVM flags set deliberately rather than left at the defaults. bin/install_solr_service.sh (Linux only) does the first part: given a downloaded archive, it extracts Solr under /opt, creates a dedicated solr user, and registers a systemd (or init.d) service that starts on boot:

# Extract, install as a service running as user "solr", and start it.
sudo bash ./install_solr_service.sh solr-10.0.0.tgz -u solr -s solr -p 8983
sudo service solr status
# https://solr.apache.org/guide/solr/latest/deployment-guide/taking-solr-to-production.html

The installer writes an environment file, /etc/default/solr.in.sh, that bin/solr sources on every start; production tuning goes there rather than as ad hoc flags on the command line.

  • SOLR_HEAP — the -Xms/-Xmx JVM heap size (bin/solr start -m sets the same thing for a manual start). Undersized heaps show up as OutOfMemoryError; oversized ones just take memory away from the OS page cache that Lucene relies on for fast reads — both -Xms and -Xmx should be set to the same value so the heap never resizes at runtime.

  • Ulimits — Solr opens one file descriptor per open segment file (times replicas, times collections) and, under SolrCloud, many concurrent threads; the reference guide’s stated minimums are 65,000 open files and 65,000 max processes/threads, raised in /etc/security/limits.conf (or the service’s own limit directives) rather than relying on the OS default of 1024.

  • SOLR_OPTS — the catch-all environment variable for extra JVM flags (GC tuning, JMX, custom system properties such as -Dsolr.packages.enabled=true, see the package manager below) appended to every start without editing bin/solr itself.

See Taking Solr to Production for the full checklist, including running Solr behind a reverse proxy, disabling swap, and hostname/SOLR_HOST configuration for nodes with multiple network interfaces.

Solr in Docker, and the Solr Operator on Kubernetes

The official solr image on Docker Hub runs a single node; solr-precreate bootstraps one core on first start, and SolrCloud mode is selected by pointing every container at the same ZooKeeper ensemble through ZK_HOST — both shown with a runnable example in What Apache Solr is & how to run it. Beyond a single container or a hand-written Compose file, running a multi-node SolrCloud cluster on Kubernetes — ZooKeeper, rolling upgrades, backups and scaling as Kubernetes custom resources — is the job of the community-maintained Solr Operator, which is linked here rather than documented in depth:

# Not run here -- see the Solr Operator's own install docs for the current Helm chart and CRDs.
helm repo add apache-solr https://solr.apache.org/charts
helm install solr-operator apache-solr/solr-operator

See Solr in Docker for image tags, environment variables and the Compose walk-through, which also links out to the Solr Operator project for the Kubernetes path.

Backup & restore

A Collections API BACKUP writes a collection’s index files plus its configset to a shared repository location; RESTORE recreates it from there, including under a new name or onto a differently-shaped cluster. This is the SolrCloud path already introduced in Collections API, configsets & replica placement; the sequence in full:

# Take a backup of "books" to a shared filesystem location every node can reach.
curl "http://localhost:8983/solr/admin/collections?action=BACKUP&name=books-2026-09-08\
&collection=books&location=/mnt/solr-backups"

# Poll status for an async backup (pass async=<id> on BACKUP to get one).
curl "http://localhost:8983/solr/admin/collections?action=REQUESTSTATUS&requestid=<id>"

# Restore into a new collection from that backup.
curl "http://localhost:8983/solr/admin/collections?action=RESTORE&name=books-2026-09-08\
&collection=books-restored&location=/mnt/solr-backups"
# https://solr.apache.org/guide/solr/latest/deployment-guide/backup-restore.html

Repositories are pluggable: a local/shared filesystem path (location, the default), or a registered S3BackupRepository / GCSBackupRepository for object storage, configured once in solr.xml and then referenced by name (repository=<name>) on the BACKUP call instead of location. Backups taken against the same repository are incremental — each one stores only the Lucene segment files not already present from an earlier backup of that collection, so steady-state backups are cheap even though the API call looks the same every time; only the first backup pays the full cost. RESTORE cannot target an existing collection name, so a restore drill always lands in a fresh (or explicitly deleted-first) collection. See Backup/Restore for the full repository configuration, the standalone-core CREATESNAPSHOT/RESTORECORE commands used outside SolrCloud, and the restore-status API.

Rolling restarts

A SolrCloud cluster with replicationFactor >= 2 can be restarted one node at a time without downtime for any collection that has a live replica elsewhere; a node hosting the only copy of a shard makes that shard briefly unavailable while it restarts. The pattern, applied per node:

# 1. Confirm cluster health before touching a node.
curl "http://localhost:8983/solr/admin/collections?action=CLUSTERSTATUS"

# 2. Stop the node, upgrade/reconfigure it, then start it again with the same
#    SOLR_HOME / ZK_HOST / SOLR_HOST settings so it rejoins as the same node.
bin/solr stop -p 8983
bin/solr start -p 8983 -z zk1:2181,zk2:2181,zk3:2181

# 3. Wait for it to recover before moving to the next node.
bin/solr healthcheck -c books -z zk1:2181,zk2:2181,zk3:2181

Save the current Overseer leader for last, since restarting it forces an Overseer re-election on top of the node’s own recovery. During the rollover the cluster runs a mix of old- and new-version nodes, which is the supported (if temporary) state for both a config-only restart and a version upgrade — see the next section. See Upgrading a SolrCloud Cluster for identifying the Overseer, pre-flight healthchecks, and the same procedure applied to a version change rather than a plain restart.

Upgrade path & Major Changes notes

An in-place SolrCloud upgrade is the same rolling-restart procedure above, with the new version’s archive/service installed on each node before it restarts, and the cluster only fully on the new version once every node has cycled through. Two things to check before starting, both called out on Upgrading a SolrCloud Cluster: back up any collection that is not replicated (a downed node makes it unavailable, not just degraded, during its own restart), and rebuild any custom plugin jars against the target version before it starts loading them.

The behavior changes to actually check for live under Upgrade Notes, one "Major Changes" page per major version. These pages are the record of why an old assumption (a removed \{! local-param syntax, an old numeric field type, a renamed setting) needs updating, not just that it changed:

  • Major Changes in Solr 10 — the notes for the line these pages track (see the disclaimer at the top of this section for the exact release).

  • Major Changes in Solr 9 — required reading when upgrading a cluster still on an 8.x configset, since several pages in this section (BM25 as the default similarity, point-based numerics replacing trie, autoscaling’s removal referenced in Collections API, configsets & replica placement) trace back to changes introduced across the 9.x line.

Skipping a major version in one hop is unsupported — ZooKeeper cluster state and configset formats are only guaranteed compatible one major version forward, so a 7.x cluster upgrades through 8.x before reaching 9.x or 10.0.

The package manager

The package manager installs and upgrades Solr plugins — packaged jars plus their manifest — cluster-wide from a trusted repository, without restarting any node. It ships disabled; enable it with a system property (in SOLR_OPTS, see above) before it will accept a repository or a package:

# Enable once per node (add to /etc/default/solr.in.sh as SOLR_OPTS="-Dsolr.packages.enabled=true").
bin/solr start -Dsolr.packages.enabled=true

# Trust a repository's signing key, then install and deploy a package to a collection.
bin/solr package add-repo my-repo https://example.com/repo
bin/solr package install my-plugin
bin/solr package deploy my-plugin -collections books
# https://solr.apache.org/guide/solr/latest/configuration-guide/package-manager.html

Because a package can load arbitrary code cluster-wide, only HTTPS repository URLs are accepted and every package is signature-verified against a trusted key before install — the same trust model already covers uploaded configsets loading <lib> jars, described in Collections API, configsets & replica placement and Security. See Package Manager for the full command reference and how to author a package manifest.

Continue with Monitoring & metrics for what to watch on a running cluster, or Security for authentication, authorization and TLS on the endpoints used throughout this page.