What Apache Solr is & how to run it

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.

Apache Solr is a standalone search server built on top of Apache Lucene. Unlike Lucene, which is a Java library you embed, Solr is a service you run: it exposes indexing and search over HTTP, with requests and responses in JSON (the default), XML, or CSV. This page explains what Solr is, the release line these pages track, how to start a node, the conventions (curl and bin/solr post) used throughout the rest of this section, and a first round-trip against a running instance.

A standalone search server over Apache Lucene

Solr wraps Lucene’s indexing and search engine with a REST-ish HTTP API, a schema layer, distributed coordination, and an administration UI. Every operation — creating a collection, indexing a document, running a query — is a plain HTTP request:

curl http://localhost:8983/solr/admin/info/system?wt=json
# https://solr.apache.org/guide/solr/latest/getting-started/introduction.html

The response is JSON by default (wt=json); pass wt=xml for XML. Documents can also be posted as XML or CSV, but JSON is what the examples in this section use. Solr’s basic unit of information is a document, a set of named fields; the shape of those fields is described by a schema. See Core concepts & architecture for collections, cores, shards, and replicas, and Schema & fields for how documents and fields are defined. For the narrative overview, read Introduction to Solr. For the field/document/schema mental model, read Documents, Fields, and Schema Design.

Releases and versions

See the disclaimer at the top of this page for the release line these pages track. Two distributions are published for each release: a full package with all bundled modules, and a slim package with minimal dependencies — the examples below assume the full package. Check the running version before relying on a feature:

bin/solr version
# https://solr.apache.org/guide/solr/latest/deployment-guide/installing-solr.html

SolrCloud vs. user-managed mode

Solr runs in one of two modes. SolrCloud is the primary, scalable mode: nodes coordinate through Apache ZooKeeper, and collections are sharded and replicated across the cluster automatically — this is the default when you run bin/solr start with no extra flags, using an embedded ZooKeeper for a single node. User-managed mode (the older name is "standalone") skips ZooKeeper entirely; a directory of independent, manually replicated cores takes the place of cluster-managed collections. This section documents SolrCloud as the default and calls out user-managed mode where the two differ, notably in User-managed mode & replication. The cluster topology itself is covered in SolrCloud architecture.

Running Solr

The `bin/solr` control script

bin/solr (bin\solr.cmd on Windows) is the command-line entry point for almost everything in this section: starting and stopping nodes, creating and deleting collections, posting documents, running health checks, and talking to ZooKeeper. The commands used most often while getting started:

Command Purpose

Command	Purpose
`start` / `restart` / `stop`	Start, restart, or stop a local Solr node.
`status`	Show JSON status for every locally running instance.
`create`	Create a collection (SolrCloud) or a core (user-managed mode).
`delete`	Remove a collection or core, optionally deleting its configset too.
`post`	Index files, directories, or raw content into a collection.
`healthcheck`	Report the health of a SolrCloud collection’s shards and replicas.
`api`	Send an arbitrary HTTP request to a Solr endpoint from the shell.

start / restart / stop

Start, restart, or stop a local Solr node.

status

Show JSON status for every locally running instance.

create

Create a collection (SolrCloud) or a core (user-managed mode).

delete

Remove a collection or core, optionally deleting its configset too.

post

Index files, directories, or raw content into a collection.

healthcheck

Report the health of a SolrCloud collection’s shards and replicas.

api

Send an arbitrary HTTP request to a Solr endpoint from the shell.

Useful flags on start/restart: -p <port> (default 8983), -m <heap> (default 512m), -e <example> to launch a preloaded example configuration (cloud, techproducts, schemaless, and others), -z <zkHost> to join an external ZooKeeper ensemble instead of the embedded one, and --user-managed to start outside SolrCloud entirely. The full command and flag reference is Solr Control Script Reference.

The binary archive

Download solr-10.0.0.tgz (or the matching -slim package) from the downloads page, extract it, and start it — no root and no prior install required:

tar zxf solr-10.0.0.tgz
cd solr-10.0.0/
bin/solr start
# Starts one SolrCloud node on port 8983 with an embedded ZooKeeper.
# https://solr.apache.org/guide/solr/latest/deployment-guide/installing-solr.html

The extracted tree separates bin/ (control script, the post tool), server/ (the running application, Admin UI, and logs), modules/ (first-party add-ons in the full package), and example/ (sample documents and configsets used by the tutorial). For a long-running install, sudo bin/install_solr_services.sh solr-10.0.0.tgz registers Solr as a service; see Installing Solr for system requirements and the service script in full.

Docker

The official image is published as solr:<version> (and solr:<version>-slim) on Docker Hub. The one-liner below starts a single node with a precreated core, backed by a bind-mounted data directory:

docker run -d --name my_solr -p 8983:8983 \
  -v "$PWD/solrdata:/var/solr" \
  solr:10.0.0 solr-precreate gettingstarted
# https://solr.apache.org/guide/solr/latest/deployment-guide/solr-in-docker.html

For SolrCloud in Docker (Compose or otherwise), point every node at the same ZooKeeper ensemble with the ZK_HOST environment variable instead of solr-precreate:

services:
  solr:
    image: solr:10.0.0
    ports: ["8983:8983"]
    environment:
      ZK_HOST: "zoo:2181"
# https://solr.apache.org/guide/solr/latest/deployment-guide/solr-in-docker.html

On Kubernetes, the community-maintained Solr Operator manages SolrCloud clusters, ZooKeeper, backups, and rolling upgrades as custom resources; it is linked, not documented in depth, from Solr in Docker.

The Admin UI

Every node serves a web console at http://<host>:<port>/solr/ (http://localhost:8983/solr/ for the single-node examples above). It shows cluster and node status, lets you run queries and inspect the schema and configset of a collection from the Query and Schema tabs, and exposes a Cloud tab with the live ZooKeeper tree when running in SolrCloud mode. It is the fastest way to sanity-check the round-trip below without writing a single curl command.

Talking to Solr: curl and `bin/solr post` conventions

Two tools cover essentially every example in this section. Direct HTTP calls use curl against the collection’s /update and /select handlers, with a JSON body and wt=json for readable output:

curl "http://localhost:8983/solr/gettingstarted/select?q=*:*&wt=json"
# https://solr.apache.org/guide/solr/latest/getting-started/introduction.html

Bulk-loading files, directories, or a whole tree of sample data uses bin/solr post instead, which wraps the same /update handler and can guess a document’s content type from its extension:

bin/solr post -c gettingstarted example/exampledocs/*.xml

Prefer curl when an example builds a request body worth reading (a query, a single document, a schema change) and bin/solr post when it is about loading a batch of sample data — that split is kept consistent across the pages in this section. For the client libraries instead of raw HTTP, jump to Spring Boot integration, which drives Solr through SolrJ.

A first round-trip

Create a collection, index one document into it, then search for it. This assumes a node already started in SolrCloud mode (bin/solr start, as above).

# 1. Create a collection with one shard and one replica.
bin/solr create -c books -s 1 -rf 1
# https://solr.apache.org/guide/solr/latest/deployment-guide/solr-control-script-reference.html

# 2. Index one document as JSON, and commit so it is immediately searchable.
curl "http://localhost:8983/solr/books/update?commit=true" \
  -H 'Content-Type: application/json' \
  -d '[
        {
          "id": "1",
          "title": "The Left Hand of Darkness",
          "author": "Ursula K. Le Guin",
          "year_i": 1969
        }
      ]'
# https://solr.apache.org/guide/solr/latest/getting-started/documents-fields-schema-design.html

# 3. Fetch it back by id.
curl "http://localhost:8983/solr/books/get?id=1"

# 4. Full-text search: the default query parser tokenizes "darkness" and scores hits with BM25.
curl "http://localhost:8983/solr/books/select?q=title:darkness"

The response wraps hits in response.docs[], each with its stored fields and, once fl=score is requested, a relevance score (BM25 is the default similarity in Solr, and has been since Solr 6 — this is not the classic TF/IDF similarity of older references). year_i uses the _i dynamic-field suffix so Solr resolves it to a point-based integer field without an explicit schema edit; Solr’s numeric field types have been point-based since the older, slower trie numeric types were removed. From here:

Core concepts & architecture — what a collection, shard, replica, and core actually are, and how they map onto the commands used above.
Schema & fields — the managed schema, explicit vs. dynamic fields, and the uniqueKey used as id above.
Indexing & updates — the /update handler in depth, commits vs. soft commits, and deleting documents.
Query basics & parameters — the /select request shape, common parameters, and paging through results.
SolrCloud architecture — how -s/-rf above translate into shards and replicas across a real cluster.

For readers coming from Elasticsearch, Solr vs. Elasticsearch maps this same round-trip onto the Elasticsearch section; for choosing between the two (or another store) up front, see Choosing the Right Database. The reference walk-through for this sequence is Solr Tutorial.

Continue with Core concepts & architecture.