SOLR-17468: Put SolrCloud docs first in Ref Guide (#2730)

For each place where we refer to Cloud and non cloud, move Cloud first.  Likewise where we refer to something that impacts collections and cores, make sure Collection is first.  This aligns with us moving to running in Cloud mode by default.

dev-docs/apis.adoc

@@ -81,4 +81,3 @@ A good example for each of these steps can be seen in Solr's v2 "add-replica-pro
 While we've settled on JAX-RS as our framework for defining v2 APIs going forward, Solr still retains many v2 APIs that were written using an older homegrown framework.
 This framework defines APIs using annotations (e.g. `@EndPoint`) similar to those used by JAX-RS, but lacks the full range of features and 3rd-party tooling.
 We're in the process of migrating these API definitions to JAX-RS and hope to remove all support for this legacy framework in a future release.
-

solr/solr-ref-guide/modules/configuration-guide/pages/config-sets.adoc

@@ -24,9 +24,45 @@ Such configuration, _configsets_, can be named and then referenced by collection
 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 SolrCloud Clusters
+
+In SolrCloud, it's critical to understand that configsets are stored in ZooKeeper _and not_ in the file system.
+Solr's `_default` configset is uploaded to ZooKeeper on initialization.
+This and a couple of example configsets remain on the file system but Solr does not use them unless they are used with a new collection.
+
+When you create a collection in SolrCloud, you can specify a named configset.
+If you don't, then the `_default` will be copied and given a unique name for use by the new collection.
+
+A configset can be uploaded to ZooKeeper either via the xref:configsets-api.adoc[] or more directly via xref:deployment-guide: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 xref:deployment-guide: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 xref:deployment-guide:zookeeper-ensemble.adoc#increasing-the-file-size-limit[increase the ZooKeeper file size limit] or store them xref:libs.adoc#lib-directives-in-solrconfig[on the filesystem] of every node in a cluster.
+
+=== Forbidden File Types
+
+Solr does not accept all file types when uploading or downloading configSets.
+By default the excluded file types are:
+
+- `class`
+- `java`
+- `jar`
+- `tgz`
+- `zip`
+- `tar`
+- `gz`
+
+However, users can impose stricter or looser limits on their systems by providing a comma separated list of file types
+(without the preceding dot, e.g. `jar,class,csv`), to either of the following settings:
+
+- System Property: `-DsolrConfigSetForbiddenFileTypes`
+- Environment Variable: `SOLR_CONFIG_SET_FORBIDDEN_FILE_TYPES`
+
 == Configsets in User-Managed Clusters or Single-Node Installations
 
-If you are using Solr in a user-managed cluster or a single-node installation, configsets are managed on the filesystem.
+If you are using Solr in a If you are using Solr in a user-managed cluster or a single-node installation, configsets are managed on the filesystem. installation, 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.
@@ -81,39 +117,3 @@ curl -v -X POST -H 'Content-type: application/json' -d '{
 ----
 ====
 ======
-
-== Configsets in SolrCloud Clusters
-
-In SolrCloud, it's critical to understand that configsets are stored in ZooKeeper _and not_ the file system.
-Solr's `_default` configset is uploaded to ZooKeeper on initialization.
-This and a couple of example configsets remain on the file system but Solr does not use them unless they are used with a new collection.
-
-When you create a collection in SolrCloud, you can specify a named configset.
-If you don't, then the `_default` will be copied and given a unique name for use by the new collection.
-
-A configset can be uploaded to ZooKeeper either via the xref:configsets-api.adoc[] or more directly via xref:deployment-guide: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 xref:deployment-guide: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 xref:deployment-guide:zookeeper-ensemble.adoc#increasing-the-file-size-limit[increase the ZooKeeper file size limit] or store them xref:libs.adoc#lib-directives-in-solrconfig[on the filesystem] of every node in a cluster.
-
-=== Forbidden File Types
-
-Solr does not accept all file types when uploading or downloading configSets.
-By default the excluded file types are:
-
-- `class`
-- `java`
-- `jar`
-- `tgz`
-- `zip`
-- `tar`
-- `gz`
-
-However, users can impose stricter or looser limits on their systems by providing a comma separated list of file types
-(without the preceding dot, e.g. `jar,class,csv`), to either of the following settings:
-
-- System Property: `-DsolrConfigSetForbiddenFileTypes`
-- Environment Variable: `SOLR_CONFIG_SET_FORBIDDEN_FILE_TYPES`

solr/solr-ref-guide/modules/deployment-guide/deployment-nav.adoc

@@ -32,9 +32,6 @@
 
 * Scaling Solr
 ** xref:cluster-types.adoc[]
-** User-Managed Clusters
-*** xref:user-managed-index-replication.adoc[]
-*** xref:user-managed-distributed-search.adoc[]
 ** SolrCloud Clusters
 *** xref:solrcloud-shards-indexing.adoc[]
 *** xref:solrcloud-recoveries-and-write-tolerance.adoc[]
@@ -55,6 +52,9 @@
 *** Admin UI
 **** xref:collections-core-admin.adoc[]
 **** xref:cloud-screens.adoc[]
+** User-Managed Clusters
+*** xref:user-managed-index-replication.adoc[]
+*** xref:user-managed-distributed-search.adoc[]
 
 * Monitoring Solr
 ** xref:configuring-logging.adoc[]

solr/solr-ref-guide/modules/deployment-guide/pages/cluster-types.adoc

@@ -21,6 +21,8 @@ A Solr cluster is a group of servers (_nodes_) that each run Solr.
 There are two general modes of operating a cluster of Solr nodes.
 One mode provides central coordination of the Solr nodes (<<SolrCloud Mode>>), while the other allows you to operate a cluster without this central coordination (<<User-Managed Mode>>).
 
+TIP: "User Managed" and "Single Node" are sometimes referred to as "Standalone", especially in source code.
+
 Both modes share general concepts, but ultimately differ in how those concepts are reflected in functionality and features.
 
 First let's cover a few general concepts and then outline the differences between the two modes.
@@ -88,7 +90,7 @@ As long as one replica of each relevant shard is available, a user query or inde
 
 == User-Managed Mode
 
-Solr's user-managed mode requires that cluster coordination activities that SolrCloud normally uses ZooKeeper for are performed manually or with local scripts.
+Solr's user-managed mode requires that cluster coordination activities that SolrCloud normally uses ZooKeeper for tp be performed manually or with local scripts.
 
 If the corpus of documents is too large for a single-sharded index, the logic to create shards is entirely left to the user.
 There are no automated or programmatic ways for Solr to create shards during indexing.

solr/solr-ref-guide/modules/deployment-guide/pages/enabling-ssl.adoc

@@ -132,9 +132,11 @@ They are mutually exclusive and Jetty will select one of them which may not be w
 
 When you start Solr, the `bin/solr` script includes these settings and will pass them as system properties to the JVM.
 
+If you are using SolrCloud, you need to <<Configure ZooKeeper>> before starting Solr.
+
 If you are running Solr in a user-managed cluster or single-node installation, you can skip to <<Start User-Managed Cluster or Single-Node Solr>>.
 
-If you are using SolrCloud, however, you need to <<Configure ZooKeeper>> before starting Solr.
+
 
 === Password Distribution via Hadoop Credential Store
 
@@ -268,19 +270,23 @@ Once this and all other steps are complete, you can go ahead and start Solr.
 
 == Starting Solr After Enabling SSL
 
-=== Start User-Managed Cluster or Single-Node Solr
+=== Start SolrCloud
 
-Start Solr using the Solr control script as shown in the examples below.
-Customize the values for the parameters shown as needed and add any used in your system.
+NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see xref:zookeeper-ensemble.adoc#updating-solr-include-files[Updating Solr Include Files]) you can omit `-z <zk host string>` from all of the `bin/solr`/`bin\solr.cmd` commands below.
 
-[tabs#single]
+Start each Solr node with the Solr control script as shown in the examples below.
+Customize the values for the parameters shown as necessary and add any used in your system.
+
+If you created the SSL key without all DNS names or IP addresses on which Solr nodes run, you can tell Solr to skip hostname verification for inter-node communications by setting the `-Dsolr.ssl.checkPeerName=false` system property.
+
+[tabs#cloud]
 ======
 *nix::
 +
 ====
 [source,terminal]
 ----
-$ bin/solr start -p 8984
+$ bin/solr start --cloud --solr-home cloud/node1 -z server1:2181,server2:2181,server3:2181 -p 8984
 ----
 ====
 
@@ -289,28 +295,25 @@ Windows::
 ====
 [source,powershell]
 ----
-C:\> bin\solr.cmd -p 8984
+C:\> bin\solr.cmd --cloud --solr-home cloud\node1 -z server1:2181,server2:2181,server3:2181
+
 ----
 ====
 ======
 
-=== Start SolrCloud
-
-NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see xref:zookeeper-ensemble.adoc#updating-solr-include-files[Updating Solr Include Files]) you can omit `-z <zk host string>` from all of the `bin/solr`/`bin\solr.cmd` commands below.
-
-Start each Solr node with the Solr control script as shown in the examples below.
-Customize the values for the parameters shown as necessary and add any used in your system.
+=== Start User-Managed Cluster or Single-Node Solr
 
-If you created the SSL key without all DNS names or IP addresses on which Solr nodes run, you can tell Solr to skip hostname verification for inter-node communications by setting the `-Dsolr.ssl.checkPeerName=false` system property.
+Start Solr using the Solr control script as shown in the examples below.
+Customize the values for the parameters shown as needed and add any used in your system.
 
-[tabs#cloud]
+[tabs#single]
 ======
 *nix::
 +
 ====
 [source,terminal]
 ----
-$ bin/solr start --cloud --solr-home cloud/node1 -z server1:2181,server2:2181,server3:2181 -p 8984
+$ bin/solr start -p 8984
 ----
 ====
 
@@ -319,8 +322,7 @@ Windows::
 ====
 [source,powershell]
 ----
-C:\> bin\solr.cmd --cloud --solr-home cloud\node1 -z server1:2181,server2:2181,server3:2181
-
+C:\> bin\solr.cmd -p 8984
 ----
 ====
 ======

solr/solr-ref-guide/modules/deployment-guide/pages/installing-solr.adoc

@@ -171,14 +171,14 @@ To use it to start Solr you can simply enter:
 
 [source,bash]
 ----
-bin/solr start
+bin/solr start --cloud
 ----
 
 If you are running Windows, you can start Solr by running `bin\solr.cmd` instead.
 
 [source,plain]
 ----
-bin\solr.cmd start
+bin\solr.cmd start --cloud
 ----
 
 This will start Solr in the background, listening on port 8983.
@@ -195,14 +195,14 @@ For instance, to launch the "techproducts" example, you would do:
 
 [source,bash]
 ----
-bin/solr start -e techproducts
+bin/solr start --cloud -e techproducts
 ----
 
 Currently, the available examples you can run are: techproducts, schemaless, and cloud.
 See the section xref:solr-control-script-reference.adoc#running-with-example-configurations[Running with Example Configurations] for details on each example.
 
-.Getting Started with SolrCloud
-NOTE: Running the `cloud` example starts Solr in xref:cluster-types.adoc#solrcloud-mode[SolrCloud] mode.
+.Going deeper with SolrCloud
+NOTE: Running the `cloud` example demonstrates running multiple nodes of Solr using xref:cluster-types.adoc#solrcloud-mode[SolrCloud] mode.
 For more information on starting Solr in SolrCloud mode, see the section xref:getting-started:tutorial-solrcloud.adoc[].
 
 === Check if Solr is Running
@@ -227,19 +227,19 @@ image::installing-solr/SolrAdminDashboard.png[Solr's Admin UI,pdfwidth=75%]
 If Solr is not running, your browser will complain that it cannot connect to the server.
 Check your port number and try again.
 
-=== Create a Core
+=== Create a Collection
 
-If you did not start Solr with an example configuration, you would need to create a core in order to be able to index and search.
+If you did not start Solr with an example configuration, you would need to create a collection in order to be able to index and search.
 You can do so by running:
 
 [source,bash]
 ----
 bin/solr create -c <name>
 ----
 
-This will create a core that uses a data-driven schema which tries to guess the correct field type when you add documents to the index.
+This will create a collection that uses a data-driven schema which tries to guess the correct field type when you add documents to the index.
 
-To see all available options for creating a new core, execute:
+To see all available options for creating a new collection, execute:
 
 [source,bash]
 ----

solr/solr-ref-guide/modules/deployment-guide/pages/monitoring-with-prometheus-and-grafana.adoc

@@ -124,7 +124,7 @@ It can be any port not already in use on your server.
 |Optional |Default: _see description_
 |===
 +
-The Solr base URL (such as `\http://localhost:8983/solr`) when Solr is running in a user-managed cluster or a single-node installation.
+The Solr base URL (such as `\http://localhost:8983/solr`) when Solr is running in a  The Solr base URL (such as `\http://localhost:8983/solr`) when Solr is running in a user-managed cluster or a single-node installation.
 If you are running SolrCloud, do not specify this parameter.
 If neither the `-b` parameter nor the `-z` parameter are defined, the default is `-b \http://localhost:8983/solr`.
 

solr/solr-ref-guide/modules/deployment-guide/pages/rate-limiters.adoc

@@ -22,7 +22,7 @@ The default rate limiting is implemented for updates and searches.
 
 If a request exceeds the request quota, further incoming requests are rejected with HTTP error code 429 (Too Many Requests).
 
-Note that rate limiting works at an instance (JVM) level, not at a core or collection level.
+Note that rate limiting works at an instance (JVM) level, not at a collection or core level.
 Consider that when planning capacity.
 There is future work planned to have finer grained execution here (https://issues.apache.org/jira/browse/SOLR-14710[SOLR-14710]).
 

solr/solr-ref-guide/modules/deployment-guide/pages/solr-control-script-reference.adoc

@@ -633,15 +633,15 @@ Below is an example healthcheck request and response using a non-standard ZooKee
 
 The `bin/solr` script can also help you create new collections or cores, or delete collections or cores.
 
-=== Create a Core or Collection
+=== Create a Collection or Core
 
-The `create` command creates a core or collection depending on whether Solr is running in standalone (core) or SolrCloud mode (collection).
+The `create` command creates a Collection or Core depending on whether Solr is running in SolrCloud (collection) or user-managed mode (core).
 
 `bin/solr create [options]`
 
 `bin/solr create --help`
 
-==== Create Core or Collection Parameters
+==== Create Collection or Core Parameters
 
 `-c <name>`::
 +
@@ -650,7 +650,7 @@ The `create` command creates a core or collection depending on whether Solr is r
 s|Required |Default: none
 |===
 +
-Name of the core or collection to create.
+Name of the collection or core to create.
 +
 *Example*: `bin/solr create -c mycollection`
 
@@ -675,7 +675,7 @@ See the section <<Configuration Directories and SolrCloud>> below for more detai
 |===
 +
 The configuration name.
-This defaults to the same name as the core or collection.
+This defaults to the same name as the collection or core.
 +
 *Example*: `bin/solr create -n basic`
 
@@ -786,9 +786,9 @@ $ bin/solr config -c mycollection --action set-user-property --property update.a
 
 See also the section <<Set or Unset Configuration Properties>>.
 
-=== Delete Core or Collection
+=== Delete Collection or Core
 
-The `delete` command detects the mode that Solr is running in and then deletes the specified core (user-managed or single-node) or collection (SolrCloud) as appropriate.
+The `delete` command detects the mode that Solr is running in and then deletes the specified collection (SolrCloud) or core (user-managed or single-node) as appropriate.
 
 `bin/solr delete [options]`
 
@@ -799,7 +799,7 @@ If you're deleting a collection in SolrCloud mode, the default behavior is to al
 For example, if you created a collection with `bin/solr create -c contacts`, then the delete command `bin/solr delete -c contacts` will check to see if the `/configs/contacts` configuration directory is being used by any other collections.
 If not, then the `/configs/contacts` directory is removed from ZooKeeper.  You can override this behavior by passing `--delete-config false` when running this command.atom
 
-==== Delete Core or Collection Parameters
+==== Delete Collection or Core Parameters
 
 `-c <name>`::
 +
@@ -808,7 +808,7 @@ If not, then the `/configs/contacts` directory is removed from ZooKeeper.  You c
 s|Required |Default: none
 |===
 +
-Name of the core or collection to delete.
+Name of the collection or core to delete.
 +
 *Example*: `bin/solr delete -c mycoll`
 
@@ -1051,7 +1051,7 @@ To unset a previously set user-defined property, specify `--action unset-user-pr
 s|Required |Default: none
 |===
 +
-Name of the core or collection on which to change configuration.
+Name of the collection or core on which to change configuration.
 
 `--action <name>`::
 +