solr/solr-ref-guide/src/config-sets.adoc

= Configsets
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

Configsets are a set of configuration files used in a Solr installation: `solrconfig.xml`, the schema, and then <<resource-loading.adoc#,resources>> like language files, `synonyms.txt`, DIH-related configuration, and others.

Such configuration, _configsets_, can be named and then referenced by collections or cores, possibly with the intent to share them to avoid duplication.

Solr ships with two example configsets located in `server/solr/configsets`, which can be used as a base for your own. These example configsets are named `_default` and `sample_techproducts_configs`.

== Configsets in Standalone Mode

If you are using Solr in standalone mode, configsets are managed on the filesystem.

Each Solr core can have it's very own configset located beneath it in a `<instance_dir>/conf/` dir.
Here, it is not named or shared and the word _configset_ isn't found.
In Solr's early years, this was _the only way_ it was configured.

To create a named configset, add a new directory under the configset base directory.
The configset will be identified by the name of this directory.
Then add a `conf/` directory containing the configuration you want to share.
The structure should look something like this:

[source,bash]
----
/<configSetBaseDir>
    /configset1
        /conf
            /managed-schema
            /solrconfig.xml
    /configset2
        /conf
            /managed-schema
            /solrconfig.xml
----

The default base directory is `$SOLR_HOME/configsets`. This path can be configured in `solr.xml` (see <<format-of-solr-xml.adoc#,Format of solr.xml>> for details).

To create a new core using a configset, pass `configSet` as one of the core properties. For example, if you do this via the CoreAdmin API:

[.dynamic-tabs]
--

[example.tab-pane#v1use-configset]
====
[.tab-label]*V1 API*

[source,bash]
----
curl http://localhost:8983/admin/cores?action=CREATE&name=mycore&instanceDir=path/to/instance&configSet=configset2
----
====

[example.tab-pane#v2use-configset]
====
[.tab-label]*V2 API*

[source,bash]
----
curl -v -X POST -H 'Content-type: application/json' -d '{
  "create":[{
    "name": "mycore",
    "instanceDir": "path/to/instance",
    "configSet": "configSet2"}]}'
    http://localhost:8983/api/cores
----
====
--

== Configsets in SolrCloud Mode

In SolrCloud, it's critical to understand that configsets are fundamentally stored in ZooKeeper _and not_ the file system.
Solr's `_default` configset is uploaded to ZooKeeper on initialization.
This and some demonstration ones remain on the file system but Solr does not use them whatsoever in this mode.

When you create a collection in SolrCloud, you can specify a named configset -- possibly shared.
If you don't, then the `_default` will be copied and given a unique name for use by this collection.

A configset can be uploaded to ZooKeeper either via the <<configsets-api.adoc#,Configsets API>> or more directly via <<solr-control-script-reference.adoc#upload-a-configuration-set,`bin/solr zk upconfig`>>.
The Configsets API has some other operations as well, and likewise, so does the CLI.

To upload a file to a configset already stored on ZooKeeper, you can use <<solr-control-script-reference.adoc#copy-between-local-files-and-zookeeper-znodes,`bin/solr zk cp`>>.

CAUTION: By default, ZooKeeper's file size limit is 1MB. If your files are larger than this, you'll need to either <<setting-up-an-external-zookeeper-ensemble.adoc#increasing-the-file-size-limit,increase the ZooKeeper file size limit>> or store them instead <<libs.adoc#lib-directives-in-solrconfig,on the filesystem>>.