You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@solr.apache.org by ep...@apache.org on 2024/03/26 18:12:49 UTC
(solr) branch branch_9x updated: update tutorial docs (#2366)
This is an automated email from the ASF dual-hosted git repository.
epugh pushed a commit to branch branch_9x
in repository https://gitbox.apache.org/repos/asf/solr.git
The following commit(s) were added to refs/heads/branch_9x by this push:
new a70b0c1e3f2 update tutorial docs (#2366)
a70b0c1e3f2 is described below
commit a70b0c1e3f24a56e9bb299140035689e877d9f76
Author: Andrey Bozhko <an...@gmail.com>
AuthorDate: Tue Mar 26 13:12:05 2024 -0500
update tutorial docs (#2366)
Co-authored-by: Andrey Bozhko <ab...@apple.com>
---
.../pages/configuration-files.adoc | 2 +-
.../pages/solr-control-script-reference.adoc | 2 +-
.../getting-started/pages/introduction.adoc | 2 +-
.../getting-started/pages/searching-in-solr.adoc | 2 +-
.../getting-started/pages/solr-tutorial.adoc | 14 ++-
.../getting-started/pages/tutorial-aws.adoc | 111 ++++++++++++++-------
.../getting-started/pages/tutorial-diy.adoc | 4 +-
.../getting-started/pages/tutorial-solrcloud.adoc | 4 +-
8 files changed, 93 insertions(+), 48 deletions(-)
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/configuration-files.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/configuration-files.adoc
index 9cb7be6e7e8..63b5eb3f8f5 100644
--- a/solr/solr-ref-guide/modules/configuration-guide/pages/configuration-files.adoc
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/configuration-files.adoc
@@ -91,7 +91,7 @@ However, if you are running your own ZooKeeper ensemble, you would supply your o
== Files Screen
-The Files screen in the Admin UI lets you browse & view configuration files (such `solrconfig.xml` and the schema file) for the collection you selected.
+The Files screen in the Admin UI lets you browse & view configuration files (such as `solrconfig.xml` and the schema file) for the collection you selected.
.The Files Screen
image::configuration-files/files-screen.png[Files screen,height=400]
diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/solr-control-script-reference.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/solr-control-script-reference.adoc
index d8fcb33b859..b12a0f88a7f 100644
--- a/solr/solr-ref-guide/modules/deployment-guide/pages/solr-control-script-reference.adoc
+++ b/solr/solr-ref-guide/modules/deployment-guide/pages/solr-control-script-reference.adoc
@@ -322,7 +322,7 @@ The `-c` and `-cloud` options are equivalent:
If you specify a ZooKeeper connection string, such as `-z 192.168.1.4:2181`, then Solr will connect to ZooKeeper and join the cluster.
-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 `bin/solr` commands.
+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 `bin/solr` commands.
When starting Solr in SolrCloud mode, if you do not define `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` nor specify the `-z` option, then Solr will launch an embedded ZooKeeper server listening on the Solr port + 1000.
For example, if Solr is running on port 8983, then the embedded ZooKeeper will listen on port 9983.
diff --git a/solr/solr-ref-guide/modules/getting-started/pages/introduction.adoc b/solr/solr-ref-guide/modules/getting-started/pages/introduction.adoc
index 0a1dbe58285..387cb595c5f 100644
--- a/solr/solr-ref-guide/modules/getting-started/pages/introduction.adoc
+++ b/solr/solr-ref-guide/modules/getting-started/pages/introduction.adoc
@@ -44,4 +44,4 @@ Indexes can be sharded and replicated for performance and reliability, using eit
One type of cluster requires no supporting infrastructure, and instances are managed directly by administrators. The second type uses https://zookeeper.apache.org/[Apache Zookeeper^TM^] to coordinate management activities across the cluster.
Solr scaling and high availability features are so effective that some of the largest and most famous internet sites use Solr.
-A partial, typically self nominated, list of sites using Solr can be found at https://cwiki.apache.org/confluence/display/solr/PublicServers.
+A partial, typically self nominated, list of sites using Solr can be found at https://solr.apache.org/community.html#powered-by.
diff --git a/solr/solr-ref-guide/modules/getting-started/pages/searching-in-solr.adoc b/solr/solr-ref-guide/modules/getting-started/pages/searching-in-solr.adoc
index 1c13abdff3f..83d361f87b9 100644
--- a/solr/solr-ref-guide/modules/getting-started/pages/searching-in-solr.adoc
+++ b/solr/solr-ref-guide/modules/getting-started/pages/searching-in-solr.adoc
@@ -30,7 +30,7 @@ In addition, applications can be configured to allow users to override the defau
To process a search query, a request handler calls a _query parser_, which interprets the terms and parameters of a query.
Different query parsers support different syntax.
-Solr's default query parser is known as the xref:query-guide:standard-query-parser.adoc[],or more commonly the "lucene" query parser.
+Solr's default query parser is known as the xref:query-guide:standard-query-parser.adoc[], or more commonly, the "lucene" query parser.
Solr also includes the xref:query-guide:dismax-query-parser.adoc[], and the xref:query-guide:edismax-query-parser.adoc[].
The Standard query parser's syntax allows for greater precision in searches, but the DisMax query parser is much more tolerant of errors.
diff --git a/solr/solr-ref-guide/modules/getting-started/pages/solr-tutorial.adoc b/solr/solr-ref-guide/modules/getting-started/pages/solr-tutorial.adoc
index 13f6418d581..d3570c8c6a9 100644
--- a/solr/solr-ref-guide/modules/getting-started/pages/solr-tutorial.adoc
+++ b/solr/solr-ref-guide/modules/getting-started/pages/solr-tutorial.adoc
@@ -20,14 +20,18 @@
This tutorial covers getting Solr up and running, ingesting a variety of data sources into Solr collections,
and getting a feel for the Solr administrative and search interfaces.
-The tutorial is organized into three sections that each build on the one before it.
+The tutorial is organized into a number of sections that each build on the one before it.
+
The xref:tutorial-techproducts.adoc[first exercise] will ask you to start Solr, create a collection, index some basic documents, and then perform some searches.
The xref:tutorial-films.adoc[second exercise] works with a different set of data, and explores requesting facets with the dataset.
The xref:tutorial-diy.adoc[third exercise] encourages you to begin to work with your own data and start a plan for your implementation.
-Finally, we'll introduce <<Spatial Queries,spatial search>> and show you how to get your Solr instance back into a clean state.
+The tutorial also includes other, more advanced, exercises that introduce you to xref:tutorial-paramsets.adoc[ParamSets],
+xref:tutorial-vectors.adoc[vector search], xref:tutorial-solrcloud.adoc[SolrCloud], and xref:tutorial-aws.adoc[deploying Solr to AWS].
+
+Finally, we'll introduce <<Spatial Queries,spatial search>>, and show you how to get your Solr instance back into a clean state.
== Before You Begin
@@ -43,7 +47,7 @@ For best results, please run the browser showing this tutorial and the Solr serv
== Unpack Solr
Begin by unzipping the full Solr release and changing your working directory to the subdirectory where Solr was installed.
-For example, with a shell in UNIX, Cygwin, or MacOS:
+For example, with a shell in UNIX, Cygwin, or macOS:
[,console]
----
@@ -57,6 +61,10 @@ $ cd solr-{solr-full-version}/
If you'd like to know more about Solr's directory layout before moving to the first exercise, see the section xref:deployment-guide:installing-solr.adoc#directory-layout[Directory Layout] for details.
+== Start with the exercises
+
+Navigate to xref:tutorial-five-minutes.adoc[] to get started. Don't worry, you can come back to this page at a later point,
+after you're done with the exercises.
== Spatial Queries
diff --git a/solr/solr-ref-guide/modules/getting-started/pages/tutorial-aws.adoc b/solr/solr-ref-guide/modules/getting-started/pages/tutorial-aws.adoc
index 8d683cc0432..f352747b03d 100644
--- a/solr/solr-ref-guide/modules/getting-started/pages/tutorial-aws.adoc
+++ b/solr/solr-ref-guide/modules/getting-started/pages/tutorial-aws.adoc
@@ -29,10 +29,10 @@ In this guide we are going to:
* Create new _Security Group_
* Configure instances and launch
. Install, configure and start Solr on newly launched EC2 instances
-* Install system prerequisites: Java 1.8 and later
+* Install system prerequisites: Java 11 or later
* Download latest version of Solr
* Start the Solr nodes in SolrCloud mode
-. Create a collection, index documents and query the system
+. Create a collection, index documents, and query the system
* Create collection with multiple shards and replicas
* Index documents to the newly created collection
* Verify documents presence by querying the collection
@@ -129,60 +129,83 @@ $ ssh-add aws-key.pem
$ ssh -A ec2-user@<instance-public-dns>
----
+
-. While logged in to each of the AWS EC2 instances, configure Java 1.8 and download Solr:
+. While logged in to each of the AWS EC2 instances, configure Java 11 and download Solr:
+
[,console]
----
-# verify default java version packaged with AWS instances is 1.7
+# check if the AWS instance already has java installed
$ java -version
-$ sudo yum install java-1.8.0
+
+# install JDK 11
+$ sudo yum install java-11
+
+# configure JDK 11 as the default
$ sudo /usr/sbin/alternatives --config java
-# select jdk-1.8
-# verify default java version to java-1.8
+
+# verify that the default java version is now 11
$ java -version
----
+
-[,console]
+[,console,subs="attributes"]
----
# download desired version of Solr
-$ wget http://archive.apache.org/dist/solr/solr/{solr-full-version}/solr-{solr-full-version}.tgz
-# untar
+$ wget https://archive.apache.org/dist/solr/solr/{solr-full-version}/solr-{solr-full-version}.tgz
+
+# untar the archive
$ tar -zxvf solr-{solr-full-version}.tgz
-# set SOLR_HOME
+
+# configure SOLR_HOME env variable
$ export SOLR_HOME=$PWD/solr-{solr-full-version}
-# put the env variable in .bashrc
-# vim ~/.bashrc
+
+# also add the env variable to .bashrc
+$ vim ~/.bashrc
export SOLR_HOME=/home/ec2-user/solr-{solr-full-version}
----
. Resolve the Public DNS to simpler hostnames.
+
-Let’s assume AWS instances public DNS with IPv4 Public IP are as follows:
-+
-* ec2-54-1-2-3.us-east-2.compute.amazonaws.com: 54.1.2.3
-* ec2-54-4-5-6.us-east-2.compute.amazonaws.com: 54.4.5.6
+Let’s assume the public DNS hostnames and IPv4 addresses of EC2 instances are as follows:
+
+* ec2-101-1-2-3.us-east-2.compute.amazonaws.com: 101.1.2.3 (public), 172.16.2.3 (private)
+* ec2-101-4-5-6.us-east-2.compute.amazonaws.com: 101.4.5.6 (public), 172.16.5.6 (private)
+
-Edit `/etc/hosts`, and add entries for the above machines:
+Edit `/etc/hosts` on each of the instances, and add the following entries:
+
[,console]
----
$ sudo vim /etc/hosts
-54.1.2.3 solr-node-1
-54.4.5.6 solr-node-2
+172.16.2.3 solr-node-1
+172.16.5.6 solr-node-2
----
. Configure Solr in running EC2 instances.
+
-In this case, one of the machines will host ZooKeeper embedded along with Solr node, say, `ec2-101-1-2-3.us-east-2.compute.amazonaws.com` (aka, `solr-node-1`)
+In this case, one of the machines will host ZooKeeper embedded along with Solr node, say, `ec2-101-1-2-3.us-east-2.compute.amazonaws.com` (aka, `solr-node-1`).
++
+See <<Deploying with External ZooKeeper>> for configuring external ZooKeeper.
++
+On both machines, edit the `solr.in.sh` script and configure the environment variables that allow
+Solr and embedded ZooKeeper to listen on all network interfaces, and not just on 127.0.0.1
++
+[,console]
+----
+$ cd $SOLR_HOME
+
+# uncomment and edit the two variables
+# vim bin/solr.in.sh
+SOLR_JETTY_HOST="0.0.0.0"
+SOLR_ZK_EMBEDDED_HOST="0.0.0.0"
+----
+
-See <<Deploying with External ZooKeeper>> for configure external ZooKeeper.
+See xref:deployment-guide:securing-solr.adoc#network-configuration[Network Configuration] for more details.
+
Inside the `ec2-101-1-2-3.us-east-2.compute.amazonaws.com` (`solr-node-1`)
+
[,console]
----
$ cd $SOLR_HOME
-# start Solr node on 8983 and ZooKeeper will start on 8983+1000 9983
+
+# start Solr node on 8983 and ZooKeeper will start on 9983 (8983+1000)
$ bin/solr start -c -p 8983 -h solr-node-1
----
+
@@ -191,23 +214,24 @@ On the other node, `ec2-101-4-5-6.us-east-2.compute.amazonaws.com` (`solr-node-2
[,console]
----
$ cd $SOLR_HOME
+
# start Solr node on 8983 and connect to ZooKeeper running on first node
$ bin/solr start -c -p 8983 -h solr-node-2 -z solr-node-1:9983
----
. Inspect and Verify.
-Inspect the Solr nodes state from browser on local machine:
+
+Inspect the Solr nodes state from browser on local machine.
Go to:
+
[source,bash]
----
-http://ec2-101-1-2-3.us-east-2.compute.amazonaws.com:8983/solr (solr-node-1:8983/solr)
+http://ec2-101-1-2-3.us-east-2.compute.amazonaws.com:8983/solr
-http://ec2-101-4-5-6.us-east-2.compute.amazonaws.com:8983/solr (solr-node-2:8983/solr)
+http://ec2-101-4-5-6.us-east-2.compute.amazonaws.com:8983/solr
----
+
-You should able to see Solr UI dashboard for both nodes.
+You should be able to see Solr UI dashboard for both nodes.
== Create Collection, Index and Query
@@ -223,9 +247,9 @@ If you want to configure an external ZooKeeper ensemble to avoid using the embed
+
[source,text,subs="verbatim"]
$ sudo vim /etc/hosts
-54.1.2.3 solr-node-1
-54.4.5.6 solr-node-2
-54.7.8.9 zookeeper-node
+172.16.2.3 solr-node-1
+172.16.5.6 solr-node-2
+172.16.8.9 zookeeper-node
* You'll need to install ZooKeeper manually, described in the next section.
@@ -239,12 +263,13 @@ See the section xref:deployment-guide:zookeeper-ensemble.adoc[] for information
In this example we're using ZooKeeper v{dep-version-zookeeper}.
On the node you're using to host ZooKeeper (`zookeeper-node`), download the package and untar it:
+
-[,console]
+[,console,subs="attributes"]
----
-# download stable version of ZooKeeper, here {dep-version-zookeeper}
-$ wget https://archive.apache.org/dist/zookeeper/zookeeper-{dep-version-zookeeper}/apache-zookeeper-{dep-version-zookeeper}.tar.gz
-# untar
-$ tar -zxvf apache-zookeeper-{dep-version-zookeeper}.tar.gz
+# download stable version of ZooKeeper
+$ wget https://archive.apache.org/dist/zookeeper/zookeeper-{dep-version-zookeeper}/apache-zookeeper-{dep-version-zookeeper}-bin.tar.gz
+
+# untar the archive
+$ tar -zxvf apache-zookeeper-{dep-version-zookeeper}-bin.tar.gz
----
+
Add an environment variable for ZooKeeper's home directory (`ZOO_HOME`) to the `.bashrc` for the user who will be running the process.
@@ -253,16 +278,18 @@ Correct the path to the ZooKeeper installation as appropriate if where you put i
+
[source,bash,subs="attributes"]
----
-$ export ZOO_HOME=$PWD/apache-zookeeper-{dep-version-zookeeper}
+$ export ZOO_HOME=$PWD/apache-zookeeper-{dep-version-zookeeper}-bin
+
# put the env variable in .bashrc
# vim ~/.bashrc
-export ZOO_HOME=/home/ec2-user/apache-zookeeper-{dep-version-zookeeper}
+export ZOO_HOME=/home/ec2-user/apache-zookeeper-{dep-version-zookeeper}-bin
----
. Change directories to `ZOO_HOME`, and create the ZooKeeper configuration by using the template provided by ZooKeeper.
+
[,console]
----
$ cd $ZOO_HOME
+
# create ZooKeeper config by using zoo_sample.cfg
$ cp conf/zoo_sample.cfg conf/zoo.cfg
----
@@ -273,17 +300,23 @@ $ cp conf/zoo_sample.cfg conf/zoo.cfg
# create data dir for ZooKeeper, edit zoo.cfg, uncomment autopurge parameters
$ mkdir data
$ vim conf/zoo.cfg
+
# -- uncomment --
autopurge.snapRetainCount=3
autopurge.purgeInterval=1
+
# -- edit --
dataDir=data
+
+# -- add --
+4lw.commands.whitelist=mntr,conf,ruok
----
. Start ZooKeeper.
+
[,console]
----
$ cd $ZOO_HOME
+
# start ZooKeeper, default port: 2181
$ bin/zkServer.sh start
----
@@ -293,6 +326,7 @@ $ bin/zkServer.sh start
[,console]
----
$ cd $SOLR_HOME
+
# start Solr node on 8983 and connect to ZooKeeper running on ZooKeeper node
$ bin/solr start -c -p 8983 -h solr-node-1 -z zookeeper-node:2181
----
@@ -302,8 +336,9 @@ $ bin/solr start -c -p 8983 -h solr-node-1 -z zookeeper-node:2181
[,console]
----
$ cd $SOLR_HOME
+
# start Solr node on 8983 and connect to ZooKeeper running on ZooKeeper node
-$ bin/solr start -c -p 8983 -h solr-node-1 -z zookeeper-node:2181
+$ bin/solr start -c -p 8983 -h solr-node-2 -z zookeeper-node:2181
----
[TIP]
diff --git a/solr/solr-ref-guide/modules/getting-started/pages/tutorial-diy.adoc b/solr/solr-ref-guide/modules/getting-started/pages/tutorial-diy.adoc
index 8a953676e99..6a1fc1d26d7 100644
--- a/solr/solr-ref-guide/modules/getting-started/pages/tutorial-diy.adoc
+++ b/solr/solr-ref-guide/modules/getting-started/pages/tutorial-diy.adoc
@@ -20,7 +20,7 @@
[[exercise-3]]
== Exercise 3: Index Your Own Data
-For this last exercise, work with a dataset of your choice.
+For this exercise, work with a dataset of your choice.
This can be files on your local hard drive, a set of data you have worked with before, or maybe a sample of the data you intend to index to Solr for your production application.
This exercise is intended to get you thinking about what you will need to do for your application:
@@ -120,3 +120,5 @@ You can also modify the above to only delete documents that match a specific que
At this point, you're ready to start working on your own.
Jump ahead to the overall xref:solr-tutorial.adoc#wrapping-up[wrap up] when you're ready to stop Solr and remove all the examples you worked with and start fresh.
+
+Or if you'd like, you could work your way through the remaining exercises.
diff --git a/solr/solr-ref-guide/modules/getting-started/pages/tutorial-solrcloud.adoc b/solr/solr-ref-guide/modules/getting-started/pages/tutorial-solrcloud.adoc
index d0803075a38..54c7d531edc 100644
--- a/solr/solr-ref-guide/modules/getting-started/pages/tutorial-solrcloud.adoc
+++ b/solr/solr-ref-guide/modules/getting-started/pages/tutorial-solrcloud.adoc
@@ -190,12 +190,12 @@ Notice that you need to specify the ZooKeeper address (`-z localhost:9983`) when
=== Adding a Node to a Cluster
Adding a node to an existing cluster is a bit advanced and involves a little more understanding of Solr.
-Once you startup a SolrCloud cluster using the startup scripts, you can add a new node to it by:
+Once you start a SolrCloud cluster using the startup scripts, you can add a new node to it by:
[,console]
----
$ mkdir <solr.home for new Solr node>
-$ bin/solr start -cloud -s solr.home/solr -p <port num> -z <zk hosts string>
+$ bin/solr start -cloud -s <solr.home>/solr -p <port num> -z <zk hosts string>
----
Notice that the above requires you to create a Solr home directory.