SOLR-17467: Start solr in Cloud mode, introduce --user-managed switch for User Managed mode (#2729)

Flip the default start mode to SolrCloud.  Update the docs and the tests and the tutorials.   This PR doesn't do anything to help an existing setup upgrade however.

Author: epugh

dev-docs/running-in-docker.adoc

@@ -8,7 +8,7 @@ To run Solr in a container and expose the Solr port, run:
 
 In order to start Solr in cloud mode, run the following.
 
-`docker run -p 8983:8983 solr solr-fg -c`
+`docker run -p 8983:8983 solr solr-fg`
 
 For documentation on using the official docker builds, please refer to the https://hub.docker.com/_/solr[DockerHub page].
 Up-to-date documentation for running locally built images of this branch can be found in the xref:_running_solr_in_docker[local reference guide].
@@ -30,4 +30,4 @@ For more info on building an image, run:
 `./gradlew helpDocker`
 
 == Additional Information
-You can find additional information in the https://solr.apache.org/guide/solr/latest/deployment-guide/solr-in-docker.html[Solr Ref Guide Docker Page]
+You can find additional information in the https://solr.apache.org/guide/solr/latest/deployment-guide/solr-in-docker.html[Solr Ref Guide Docker Page]

solr/CHANGES.txt

@@ -10,6 +10,8 @@ New Features
 ---------------------
 * SOLR-14496: Solr CLI commands now can interact with a Solr secured using Basic Authentication.  (Eric Pugh)
 
+* SOLR-17467: Solr CLI bin/solr start defaults to starting Solr in Cloud mode, use --user-managed switch for User Managed (aka Standalone) mode.  (Eric Pugh) 
+
 Improvements
 ---------------------
 

solr/bin/solr

@@ -367,14 +367,13 @@ function print_usage() {
 
   if [[ "$CMD" == "start" || "$CMD" == "restart" ]]; then
     echo ""
-    echo "Usage: solr $CMD [-f] [-c] [--host host] [-p port] [--server-dir directory] [-z zkHost] [-m memory] [-e example] [--solr-home solr.solr.home] [--data-home solr.data.home] [--jvm-opts \"jvm-opts\"] [-V]"
+    echo "Usage: solr $CMD [-f] [--user-managed] [--host host] [-p port] [--server-dir directory] [-z zkHost] [-m memory] [-e example] [--solr-home solr.solr.home] [--data-home solr.data.home] [--jvm-opts \"jvm-opts\"] [--verbose]"
     echo ""
     echo "  -f                    Start Solr in foreground; default starts Solr in the background"
     echo "                          and sends stdout / stderr to solr-PORT-console.log"
     echo ""
-    echo "  -c or --cloud         Start Solr in SolrCloud mode; if -z not supplied and ZK_HOST not defined in"
-    echo "                          solr.in.sh, an embedded ZooKeeper instance is started on Solr port+1000,"
-    echo "                          such as 9983 if Solr is bound to 8983"
+    echo "  --user-managed        Start Solr in user managed aka standalone mode"
+    echo "                          See the Ref Guide for more details: https://solr.apache.org/guide/solr/latest/deployment-guide/cluster-types.html"
     echo ""
     echo "  --host <host>         Specify the hostname for this Solr instance"
     echo ""
@@ -385,7 +384,7 @@ function print_usage() {
     echo ""
     echo "  --server-dir <dir>   Specify the Solr server directory; defaults to server"
     echo ""
-    echo "  -z/--zk-host <zkHost> Zookeeper connection string; only used when running in SolrCloud mode using -c"
+    echo "  -z/--zk-host <zkHost> Zookeeper connection string; ignored when running in User Managed (--user-managed) mode."
     echo "                          If neither ZK_HOST is defined in solr.in.sh nor the -z parameter is specified,"
     echo "                          an embedded ZooKeeper instance will be launched."
     echo "                          Set the ZK_CREATE_CHROOT environment variable to true if your ZK host has a chroot path, and you want to create it automatically."
@@ -733,13 +732,14 @@ FORCE=false
 SOLR_OPTS=(${SOLR_OPTS:-})
 SCRIPT_SOLR_OPTS=()
 PASS_TO_RUN_EXAMPLE=()
+SOLR_MODE="solrcloud"
 
 if [ $# -gt 0 ]; then
   while true; do
     case "${1:-}" in
-        -c|--cloud|-cloud)
-            SOLR_MODE="solrcloud"
-            PASS_TO_RUN_EXAMPLE+=("-c")
+        --user-managed)
+            SOLR_MODE="user-managed"
+            PASS_TO_RUN_EXAMPLE+=("--user-managed")
             shift
         ;;
         -d|--dir|-dir|--server-dir)
@@ -821,7 +821,6 @@ if [ $# -gt 0 ]; then
               exit 1
             fi
             ZK_HOST="$2"
-            SOLR_MODE="solrcloud"
             PASS_TO_RUN_EXAMPLE+=("-z" "$ZK_HOST")
             shift 2
         ;;
@@ -1141,11 +1140,6 @@ if [ "${#GC_LOG_OPTS[@]}" -gt 0 ]; then
   fi
 fi
 
-# If ZK_HOST is defined, the assume SolrCloud mode
-if [[ -n "${ZK_HOST:-}" ]]; then
-  SOLR_MODE="solrcloud"
-fi
-
 if [ "${SOLR_MODE:-}" == 'solrcloud' ]; then
   : "${ZK_CLIENT_TIMEOUT:=30000}"
   CLOUD_MODE_OPTS=("-DzkClientTimeout=$ZK_CLIENT_TIMEOUT")

solr/bin/solr.cmd

@@ -307,14 +307,13 @@ goto done
 
 :start_usage
 @echo.
-@echo Usage: solr %SCRIPT_CMD% [-f] [-c] [--host hostname] [-p port] [--server-dir directory] [-z zkHost] [-m memory] [-e example] [--solr-home solr.solr.home] [--data-home solr.data.home] [--jvm-opts "jvm-opts"] [-V]
+@echo Usage: solr %SCRIPT_CMD% [-f] [--user-managed] [--host hostname] [-p port] [--server-dir directory] [-z zkHost] [-m memory] [-e example] [--solr-home solr.solr.home] [--data-home solr.data.home] [--jvm-opts "jvm-opts"] [--verbose]
 @echo.
 @echo   -f            Start Solr in foreground; default starts Solr in the background
 @echo                   and sends stdout / stderr to solr-PORT-console.log
 @echo.
-@echo   -c or --cloud Start Solr in SolrCloud mode; if -z not supplied and ZK_HOST not defined in
-@echo                   solr.in.cmd, an embedded ZooKeeper instance is started on Solr port+1000,
-@echo                   such as 9983 if Solr is bound to 8983
+@echo   --user-managed Start Solr in user managed aka standalone mode"
+@echo                   See the Ref Guide for more details: https://solr.apache.org/guide/solr/latest/deployment-guide/cluster-types.html
 @echo.
 @echo   --host host   Specify the hostname for this Solr instance
 @echo.
@@ -401,9 +400,7 @@ IF "%1"=="--verbose" goto set_verbose
 IF "%1"=="-v" goto set_verbose
 IF "%1"=="-q" goto set_warn
 IF "%1"=="--quiet" goto set_warn
-IF "%1"=="-c" goto set_cloud_mode
-IF "%1"=="-cloud" goto set_cloud_mode
-IF "%1"=="--cloud" goto set_cloud_mode
+IF "%1"=="--user-managed" goto set_user_managed_mode
 IF "%1"=="-d" goto set_server_dir
 IF "%1"=="--dir" goto set_server_dir
 IF "%1"=="--server-dir" goto set_server_dir
@@ -462,8 +459,8 @@ set SOLR_LOG_LEVEL=WARN
 SHIFT
 goto parse_args
 
-:set_cloud_mode
-set SOLR_MODE=solrcloud
+:set_user_managed_mode
+set SOLR_MODE=user-managed
 SHIFT
 goto parse_args
 
@@ -875,7 +872,7 @@ IF "%SCRIPT_CMD%"=="start" (
       )
     )
   )
-  
+
   IF "%EMPTY_ADDL_JVM_ARGS%"=="true" (
     set "SCRIPT_ERROR=JVM options are required when using the -a or --jvm-opts option!"
     goto err
@@ -907,6 +904,7 @@ if !JAVA_MAJOR_VERSION! LSS 9  (
 )
 
 IF NOT "%ZK_HOST%"=="" set SOLR_MODE=solrcloud
+IF NOT "%SOLR_MODE%"=="" set SOLR_MODE=solrcloud
 
 IF "%SOLR_MODE%"=="solrcloud" (
   IF "%ZK_CLIENT_TIMEOUT%"=="" set "ZK_CLIENT_TIMEOUT=30000"
@@ -942,7 +940,8 @@ IF "%SOLR_MODE%"=="solrcloud" (
 
   IF EXIST "%SOLR_HOME%\collection1\core.properties" set "CLOUD_MODE_OPTS=!CLOUD_MODE_OPTS! -Dbootstrap_confdir=./solr/collection1/conf -Dcollection.configName=myconf -DnumShards=1"
 ) ELSE (
-  set CLOUD_MODE_OPTS=
+  REM change Cloud mode to User Managed mode with flag
+  set "CLOUD_MODE_OPTS=--user-managed"
   IF NOT EXIST "%SOLR_HOME%\solr.xml" (
     IF "%SOLR_SOLRXML_REQUIRED%"=="true" (
       set "SCRIPT_ERROR=Solr home directory %SOLR_HOME% must contain solr.xml!"

solr/core/src/java/org/apache/solr/cli/RunExampleTool.java

@@ -167,11 +167,10 @@ public List<Option> getOptions() {
             .required(false)
             .desc("Specify the hostname for this Solr instance.")
             .build(),
-        Option.builder("c")
-            .longOpt("cloud")
+        Option.builder()
+            .longOpt("user-managed")
             .required(false)
-            .desc(
-                "Start Solr in SolrCloud mode; if -z not supplied, an embedded ZooKeeper instance is started on Solr port+1000, such as 9983 if Solr is bound to 8983.")
+            .desc("Start Solr in User Managed mode.")
             .build(),
         Option.builder("m")
             .longOpt("memory")
@@ -263,7 +262,7 @@ protected void runExample(CommandLine cli, String exampleName) throws Exception
     String configSet =
         "techproducts".equals(exampleName) ? "sample_techproducts_configs" : "_default";
 
-    boolean isCloudMode = cli.hasOption('c');
+    boolean isCloudMode = !cli.hasOption("user-managed");
     String zkHost = cli.getOptionValue('z');
     int port =
         Integer.parseInt(
@@ -536,7 +535,7 @@ protected void runCloudExample(CommandLine cli) throws Exception {
       // start the other nodes
       for (int n = 1; n < numNodes; n++)
         startSolr(
-            new File(cloudDir, "node" + (n + 1) + "/solr"), true, cli, cloudPorts[n], zkHost, 30);
+            new File(cloudDir, "node" + (n + 1) + "/solr"), false, cli, cloudPorts[n], zkHost, 30);
     }
 
     String solrUrl = (String) nodeStatus.get("baseUrl");
@@ -612,9 +611,9 @@ protected Map<String, Object> startSolr(
     String hostArg = (host != null && !"localhost".equals(host)) ? " --host " + host : "";
     String zkHostArg = (zkHost != null) ? " -z " + zkHost : "";
     String memArg = (memory != null) ? " -m " + memory : "";
-    String cloudModeArg = cloudMode ? "--cloud " : "";
+    String cloudModeArg = cloudMode ? "" : "--user-managed";
     String forceArg = cli.hasOption("force") ? " --force" : "";
-    String verboseArg = verbose ? "-V" : "";
+    String verboseArg = verbose ? "--verbose" : "";
 
     String jvmOpts =
         cli.hasOption("jvm-opts") ? cli.getOptionValue("jvm-opts") : cli.getOptionValue('a');

solr/core/src/java/org/apache/solr/cli/SolrCLI.java

@@ -676,7 +676,7 @@ private static void printHelp() {
         "  SolrCloud example (start Solr running in SolrCloud mode using localhost:2181 to connect to Zookeeper, with 1g max heap size and remote Java debug options enabled):");
     print("");
     printGreen(
-        "    ./solr start -c -m 1g -z localhost:2181 --jvm-opts \"-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=1044\"");
+        "    ./solr start -m 1g -z localhost:2181 --jvm-opts \"-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=1044\"");
     print("");
     print(
         "  Omit '-z localhost:2181' from the above command if you have defined ZK_HOST in solr.in.sh.");

solr/core/src/test/org/apache/solr/cli/TestSolrCLIRunExample.java

@@ -115,7 +115,7 @@ public int execute(org.apache.commons.exec.CommandLine cmd) throws IOException {
       if (exe.endsWith("solr")) {
         String[] args = cmd.getArguments();
         if ("start".equals(args[0])) {
-          if (!hasFlag("--cloud", args) && !hasFlag("-c", args)) {
+          if (hasFlag("--user-managed", args)) {
             return startStandaloneSolr(args);
           }
 
@@ -336,9 +336,12 @@ public void testFilmsExample() throws Exception {
   }
 
   protected void testExample(String exampleName) throws Exception {
+    // Occasionally we want to test in User Managed mode, not the default SolrCloud mode.
+    String testStandaloneMode = LuceneTestCase.rarely() ? "--user-managed" : "";
     File solrHomeDir = new File(ExternalPaths.SERVER_HOME);
-    if (!solrHomeDir.isDirectory())
+    if (!solrHomeDir.isDirectory()) {
       fail(solrHomeDir.getAbsolutePath() + " not found and is required to run this test!");
+    }
 
     Path tmpDir = createTempDir();
     File solrExampleDir = tmpDir.toFile();
@@ -355,10 +358,15 @@ protected void testExample(String exampleName) throws Exception {
 
       String[] toolArgs =
           new String[] {
-            "-e", exampleName,
-            "--server-dir", solrServerDir.getAbsolutePath(),
-            "--example-dir", solrExampleDir.getAbsolutePath(),
-            "-p", String.valueOf(bindPort)
+            "-e",
+            exampleName,
+            "--server-dir",
+            solrServerDir.getAbsolutePath(),
+            "--example-dir",
+            solrExampleDir.getAbsolutePath(),
+            "-p",
+            String.valueOf(bindPort),
+            testStandaloneMode
           };
 
       // capture tool output to stdout

solr/docker/gradle-help.txt

@@ -78,11 +78,11 @@ Each input tasks a comma separated list of test names.
 
 Run specific tests:
    EnvVar: SOLR_DOCKER_TESTS_INCLUDE
-   Gradle Property: -Psolr.docker.tests.include
+   Gradle Property: -Psolr.docker.tests.include=cloud_multi_node_embedded_zk,demo
 
 Exclude specific tests:
    EnvVar: SOLR_DOCKER_TESTS_EXCLUDE
-   Gradle Property: -Psolr.docker.tests.exclude
+   Gradle Property: -Psolr.docker.tests.exclude=cloud_multi_node_embedded_zk,demo
 
 The docker tests can also be run concurrently, if explicitly specified.
 The parallelization is set by the number of gradle workers you have defined, this cannot be specified separately.

solr/docker/scripts/solr-create

@@ -75,4 +75,4 @@ else
     fi
 fi
 
-exec solr-fg
+exec solr-fg --user-managed

solr/docker/scripts/solr-demo

@@ -50,4 +50,4 @@ else
     fi
 fi
 
-exec solr-fg
+exec solr-fg --user-managed