From a34f9c9243b45397e2a202a30f0c7de4cab6dc7f Mon Sep 17 00:00:00 2001 From: Eric Pugh Date: Wed, 20 Jul 2022 10:19:22 -0400 Subject: [PATCH] SOLR-15242: Consolidate README.md with solr/README.md (#610) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Consolidate the ./README.md and ./solr/README.md into a new top level README.md optimized for Github. The /solr/README.adoc is now to help a developer understand what the subdirectories are all about. Introduced a new README.txt in the ./solr/packaging directory to ship with the distributions. Co-authored-by: epugh@opensourceconnections.com <> Co-authored-by: Jan Høydahl Co-authored-by: Houston Putman --- README.md | 151 ++++-------- dev-docs/FAQ.adoc | 26 ++ dev-docs/README.adoc | 81 +++++++ solr/README.adoc | 68 ++++++ solr/README.md | 228 ------------------ solr/bin/solr | 2 +- solr/bin/solr.cmd | 2 +- solr/packaging/README.txt | 85 +++++++ solr/packaging/build.gradle | 5 +- .../getting-started/getting-started-nav.adoc | 1 + .../getting-started/pages/tutorial-films.adoc | 2 +- .../pages/tutorial-five-minutes.adoc | 153 ++++++++++++ .../pages/tutorial-techproducts.adoc | 2 +- 13 files changed, 463 insertions(+), 343 deletions(-) create mode 100644 solr/README.adoc delete mode 100644 solr/README.md create mode 100644 solr/packaging/README.txt create mode 100644 solr/solr-ref-guide/modules/getting-started/pages/tutorial-five-minutes.adoc diff --git a/README.md b/README.md index 47e94065840..845f8c53b78 100644 --- a/README.md +++ b/README.md @@ -15,143 +15,74 @@ limitations under the License. --> -# Apache Solr +# Welcome to the Apache Solr project! +----------------------------------- -Apache Solr is an enterprise search platform written in Java and using [Apache Lucene](https://lucene.apache.org/). -Major features include full-text search, index replication and sharding, and -result faceting and highlighting. +Solr is the popular, blazing fast open source search platform for all your +enterprise, e-commerce, and analytics needs, built on [Apache Lucene](https://lucene.apache.org/). +For a complete description of the Solr project, team composition, source +code repositories, and other details, please see the Solr web site at +https://solr.apache.org/solr -[![Build Status](https://ci-builds.apache.org/job/Solr/job/Solr-Artifacts-main/badge/icon?subject=Solr)](https://ci-builds.apache.org/job/Solr/job/Solr-Artifacts-main/) +## Download - -## Online Documentation - -This README file only contains basic setup instructions. For more -comprehensive documentation, visit - -## Building with Gradle - -Firstly, you need to set up your development environment (OpenJDK 11 or greater). - -We'll assume that you know how to get and set up the JDK - if you -don't, then we suggest starting at https://jdk.java.net/ and learning -more about Java, before returning to this README. Solr runs with -Java 11 and later. - -As of 9.0, Solr uses [Gradle](https://gradle.org/) as the build -system. Ant build support has been removed. - -To build Solr, run (`./` can be omitted on Windows): - -`./gradlew assemble` - -NOTE: DO NOT use `gradle` command that is already installed on your machine (unless you know what you'll do). -The "gradle wrapper" (gradlew) does the job - downloads the correct version of it, setups necessary configurations. - -The first time you run Gradle, it will create a file "gradle.properties" that -contains machine-specific settings. Normally you can use this file as-is, but it -can be modified if necessary. - -The command above packages a full distribution of Solr server; the -package can be located at: - -`solr/packaging/build/solr-*` - -Note that the gradle build does not create or copy binaries throughout the -source repository so you need to switch to the packaging output folder above; -the rest of the instructions below remain identical. The packaging directory -is rewritten on each build. - -For development, especially when you have created test indexes etc, use -the `./gradlew dev` task which will copy binaries to `./solr/packaging/build/dev` -but _only_ overwrite the binaries which will preserve your test setup. - -If you want to build the documentation, type `./gradlew -p solr documentation`. +Downloads for Apache Solr distributions are available at https://solr.apache.org/downloads.html. ## Running Solr -After building Solr, the server can be started using -the `bin/solr` control scripts. Solr can be run in either standalone or -clustered (SolrCloud mode). - -To run Solr in standalone mode, run the following command from the `solr/` -directory: +### Installing Solr -`bin/solr start` - -To run Solr in clustered mode, run the following command from the `solr/` -directory: - -`bin/solr start -c` - -The `bin/solr` control script allows heavy modification of the started Solr. -Common options are described in some detail in solr/README.txt. For an -exhaustive treatment of options, run `bin/solr start -h` from the `solr/` -directory. +The Reference Guide contains an entire [Deployment Guide](https://solr.apache.org/guide/solr/latest/deployment-guide/system-requirements.html) to walk you through installing Solr. ### Running Solr in Docker You can run Solr in Docker via the [official image](https://hub.docker.com/_/solr). - -To run Solr in a container and expose the Solr port, run: - -`docker run -p 8983:8983 solr` - -In order to start Solr in clustered mode, run the following. - -`docker run -p 8983:8983 solr solr-fg -c` - -For documentation on using the official docker builds, please refer to the [DockerHub page](https://hub.docker.com/_/solr). -Up to date documentation for running locally built images of this branch can be found in the [local reference guide](solr/solr-ref-guide/modules/deployment-guide/pages/solr-in-docker.adoc). - -There is also a gradle task for building custom Solr images from your local checkout. -These local images are built identically to the official image except for retrieving the Solr artifacts locally instead of from the official release. -This can be useful for testing out local changes as well as creating custom images for yourself or your organization. -The task will output the image name to use at the end of the build. - -`./gradlew docker` - -For more info on building an image, run: - -`./gradlew helpDocker` - -Docker images can also be built from the Solr binary distribution (i.e. `solr-.tgz`). -Please refer to the [Solr Docker README](solr/docker/README.md) for more information. +Learn more about [Solr in Docker](https://solr.apache.org/guide/solr/latest/deployment-guide/solr-in-docker.html) ### Running Solr on Kubernetes Solr has official support for running on Kubernetes, in the official Docker image. Please refer to the [Solr Operator](https://solr.apache.org/operator) home for details, tutorials and instructions. -### Gradle build and IDE support +## How to Use + +Solr includes a few examples to help you get started. To run a specific example, enter: -- *IntelliJ* - IntelliJ idea can import the project out of the box. - Code formatting conventions should be manually adjusted. -- *Eclipse* - Not tested. -- *Netbeans* - Not tested. +``` + bin/solr start -e where is one of: + cloud: SolrCloud example + techproducts: Comprehensive example illustrating many of Solr's core capabilities + schemaless: Schema-less example (schema is inferred from data during indexing) + films: Example of starting with _default configset and adding explicit fields dynamically +``` +For instance, if you want to run the techproducts example, enter: -### Gradle build and tests +``` + bin/solr start -e techproducts +``` -`./gradlew assemble` will build a runnable Solr as noted above. +For a more in-depth introduction, please check out the [tutorials in the Solr Reference +Guide](https://solr.apache.org/guide/solr/latest/getting-started/solr-tutorial.html). -`./gradlew check` will assemble Solr and run all validation - tasks unit tests. -`./gradlew help` will print a list of help commands for high-level tasks. One - of these is `helpAnt` that shows the gradle tasks corresponding to ant - targets you may be familiar with. +## Support -## Contributing +- [Users Mailing List](https://solr.apache.org/community.html#mailing-lists-chat) +- Slack: Solr Community Channel. Sign up at https://s.apache.org/solr-slack +- IRC: `#solr` on [libera.chat](https://web.libera.chat/?channels=#solr) -Please review the [Contributing to Solr -Guide](https://cwiki.apache.org/confluence/display/solr/HowToContribute) for information on -contributing. -## Discussion and Support +## Get Involved +Please review the [Contributing to Solr Guide](https://cwiki.apache.org/confluence/display/solr/HowToContribute) +for information on contributing. + +To get involved in the developer community: - [Mailing Lists](https://solr.apache.org/community.html#mailing-lists-chat) +- Slack: `#solr-dev` in the `the-asf` organization. Sign up at https://the-asf.slack.com/messages/CE70MDPMF - [Issue Tracker (JIRA)](https://issues.apache.org/jira/browse/SOLR) -- IRC: `#solr` and `#solr-dev` on libera.chat -- [Slack](https://solr.apache.org/community.html#slack) +- IRC: `#solr-dev` on [libera.chat](https://web.libera.chat/?channels=#solr-dev) + +Learn more about developing Solr by reading through the developer docs in [./dev-docs](./dev-docs) source tree. diff --git a/dev-docs/FAQ.adoc b/dev-docs/FAQ.adoc index dd5163b6ebd..c4f2b002592 100644 --- a/dev-docs/FAQ.adoc +++ b/dev-docs/FAQ.adoc @@ -19,6 +19,32 @@ branch to avoid extra mailing list traffic etc. Periodically review https://github.com/apache/solr/branches/all to see if you have created a branch that can be deleted. +=== Running Solr in Docker + +You can run Solr in Docker via the [official image](https://hub.docker.com/_/solr). + +To run Solr in a container and expose the Solr port, run: + +`docker run -p 8983:8983 solr` + +In order to start Solr in cloud mode, run the following. + +`docker run -p 8983:8983 solr solr-fg -c` + +For documentation on using the official docker builds, please refer to the [DockerHub page](https://hub.docker.com/_/solr). +Up to date documentation for running locally built images of this branch can be found in the [local reference guide](solr/solr-ref-guide/src/running-solr-in-docker.adoc). + +There is also a gradle task for building custom Solr images from your local checkout. +These local images are built identically to the official image except for retrieving the Solr artifacts locally instead of from the official release. +This can be useful for testing out local changes as well as creating custom images for yourself or your organization. +The task will output the image name to use at the end of the build. + +`./gradlew docker` + +For more info on building an image, run: + +`./gradlew helpDocker` + === Whats the fastest build lifecycle for frontend work on Solr Admin? Run `gradle dev`, and then `cd ./packaging/build/dev/`. Fire up your cluster diff --git a/dev-docs/README.adoc b/dev-docs/README.adoc index bb0d17d75f9..781cd72cd54 100644 --- a/dev-docs/README.adoc +++ b/dev-docs/README.adoc @@ -29,3 +29,84 @@ However, the Ref Guide hosts it's own documentation on how to write Ref Guide co There are a number of tools related to doing development on Solr available in the `/dev-tools` directory. + +## Building Solr from Source +Download the Java 11 JDK (Java Development Kit) or later. We recommend the OpenJDK +distribution Eclipse Temurin available from https://adoptium.net/. +You will need the JDK installed, and the $JAVA_HOME/bin (Windows: %JAVA_HOME%\bin) +folder included on your command path. To test this, issue a "java -version" command +from your shell (command prompt) and verify that the Java version is 11 or later. + +Download the Apache Solr distribution, from https://solr.apache.org/downloads.html. +Unzip the distribution to a folder of your choice, e.g. C:\solr or ~/solr +Alternately, you can obtain a copy of the latest Apache Solr source code +directly from the Git repository: + + + +Solr uses [Gradle](https://gradle.org/) as the build +system. Navigate to the root of your source tree folder and issue the `./gradlew tasks` +command to see the available options for building, testing, and packaging Solr. + +`./gradlew dev` will create a Solr executable suitable for development. +cd to `./solr/packaging/build/dev` and run the `bin/solr` script +to start Solr. + +NOTE: `gradlew` is the "Gradle Wrapper" and will automatically download and +start using the correct version of Gradle for Solr. + +NOTE: `./gradlew help` will print a list of high-level tasks. There are also a +number of plain-text files in /help. + +The first time you run Gradle, it will create a file "gradle.properties" that +contains machine-specific settings. Normally you can use this file as-is, but it +can be modified if necessary. + +Note as well that the gradle build does not create or copy binaries throughout the +source repository so you need to switch to the packaging output folder `./solr/packaging/build`; +the rest of the instructions below remain identical. The packaging directory +is rewritten on each build. + +If you want to build the documentation, type `./gradlew -p solr documentation`. + +`./gradlew check` will assemble Solr and run all validation tasks unit tests. + +To build the final Solr artifacts run `./gradlew assemble`. + +Lastly, there is developer oriented documentation in `./dev-docs/README.adoc` that +you may find useful in working with Solr. + + +### Gradle build and IDE support + +- *IntelliJ* - IntelliJ idea can import the project out of the box. + Code formatting conventions should be manually adjusted. +- *Eclipse* - Not tested. +- *Netbeans* - Not tested. + + +### Running Solr in Docker + +You can run Solr in Docker via the [official image](https://hub.docker.com/_/solr). + +To run Solr in a container and expose the Solr port, run: + +`docker run -p 8983:8983 solr` + +In order to start Solr in cloud mode, run the following. + +`docker run -p 8983:8983 solr solr-fg -c` + +For documentation on using the official docker builds, please refer to the [DockerHub page](https://hub.docker.com/_/solr). +Up to date documentation for running locally built images of this branch can be found in the [local reference guide](solr/solr-ref-guide/src/running-solr-in-docker.adoc). + +There is also a gradle task for building custom Solr images from your local checkout. +These local images are built identically to the official image except for retrieving the Solr artifacts locally instead of from the official release. +This can be useful for testing out local changes as well as creating custom images for yourself or your organization. +The task will output the image name to use at the end of the build. + +`./gradlew docker` + +For more info on building an image, run: + +`./gradlew helpDocker` diff --git a/solr/README.adoc b/solr/README.adoc new file mode 100644 index 00000000000..d1387439cd8 --- /dev/null +++ b/solr/README.adoc @@ -0,0 +1,68 @@ +//// + 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. +//// + +== Solr Source Directories + +link:benchmark/[]:: +Benchmarking module for Solr. + +link:bin/[]:: +Scripts to startup, manage and interact with Solr instances. + +link:core/[]:: +Base Solr code. + +link:distribution/[]:: +Gradle project for building a full release of Solr. + +link:docker/[]:: +Contains a Dockerfile to build a Docker image using the source or binary distribution. +`docker/scripts` contains scripts that the Docker image uses to manage Solr. + +link:documentation/[]:: +Gradle project to build the JavaDocs site. + +link:example/[]:: +Contains example documents and an alternative Solr home +directory containing various examples. + +link:license/[]:: +Licenses, notice files and signatures for Solr dependencies. + +link:modules/[]:: +Contains modules to extend the functionality of Solr. + +link:packaging/[]:: +Gradle project to build the binary release of Solr. + +link:prometheus-exporter/[]:: +Contains a separate application to monitor Solr instances and export Prometheus metrics. + +link:server/[]:: +Gradle project that builds the Jetty server to run Solr. + +link:solr-ref-guide/[]:: +The Solr Reference Guide source files including Java examples. + +link:solrj/[]:: +Solr client code for Java applications. + +link:test-framework/[]:: +Solr test framework for internal tests and external tests integrating Solr. + +link:webapp/[]:: +Admin UI Javascript and supporting assets. diff --git a/solr/README.md b/solr/README.md deleted file mode 100644 index 944d4868210..00000000000 --- a/solr/README.md +++ /dev/null @@ -1,228 +0,0 @@ - - -Welcome to the Apache Solr project! ------------------------------------ - -Solr is the popular, blazing fast open source enterprise search platform -from the Apache Lucene project. - -For a complete description of the Solr project, team composition, source -code repositories, and other details, please see the Solr web site at -https://solr.apache.org/solr - - -Getting Started ---------------- - -All the following commands are entered from the "solr" directory which should be just below the install directory - -To start Solr for the first time after installation, simply enter: - -``` - bin/solr start -c -``` - -This will launch Solr in clustered (SolrCloud) mode, which allows you to scale out using -sharding and replication. Alternatively, you can launch a standalone Solr server -in the background of your shell, listening on port 8983. To launch Solr -in standalone mode, enter: - -``` - bin/solr start -``` - -To see all available options for starting Solr, please enter: - -``` - bin/solr start -help -``` - -After starting Solr, create either a core or collection depending on whether -Solr is running in standalone or clustered (SolrCloud) mode by entering: - -``` - bin/solr create -c -``` - -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 collection, enter: - -``` - bin/solr create -help -``` - -After starting Solr, direct your Web browser to the Solr Admin Console at: - -``` - http://localhost:8983/solr/ -``` - -When finished with your Solr installation, shut it down by executing: - -``` - bin/solr stop -all -``` - -The `-p PORT` option can also be used to identify the Solr instance to shutdown, -where more than one Solr is running on the machine. - - -Solr Examples ---------------- - -Solr includes a few examples to help you get started. To run a specific example, enter: - -``` - bin/solr -e where is one of: - - cloud : SolrCloud example - schemaless : Schema-less example (schema is inferred from data during indexing) - techproducts : Kitchen sink example providing comprehensive examples of Solr features -``` - -For instance, if you want to run the SolrCloud example, enter: - -``` - bin/solr -e cloud -``` - -Indexing Documents ---------------- - -To add documents to the index, use bin/post. For example: - -``` - bin/post -c example/exampledocs/*.xml -``` - -For more information about Solr examples please read... - - * [example/README.md](example/README.md) - -For more information about the "Solr Home" and Solr specific configuration - - * https://solr.apache.org/guide/solr-tutorial.html - -For a Solr tutorial - - * https://solr.apache.org/resources.html - -For a list of other tutorials and introductory articles. - -or linked from "docs/index.html" in a binary distribution. - -Also, there are Solr clients for many programming languages, see - - * https://cwiki.apache.org/confluence/display/solr/IntegratingSolr - - -Files included in an Apache Solr binary distribution ----------------------------------------------------- - -``` -server/ - A self-contained Solr instance, complete with a sample - configuration and documents to index. Please see: bin/solr start -help - for more information about starting a Solr server. - -bin/ - Scripts to startup, manage and interact with Solr instances. - -example/ - Contains example documents and an alternative Solr home - directory containing various examples. - -modules/ - Contains modules to extend the functionality of Solr. - Libraries for these modules can be found under modules/*/lib - -prometheus-exporter/ - Contains a separate application to monitor Solr instances and export Prometheus metrics - -docker/ - Contains a Dockerfile to build a Docker image using the source or binary distribution. - `docker/scripts` contains scripts that the Docker image uses to manage Solr. - Refer to the README.md for instructions on how to build an image. - -docs/index.html - A link to the online version of Apache Solr Javadoc API documentation and Tutorial - -licenses/ - Licenses, notice files and signatures for Solr dependencies. -``` - -Instructions for Building Apache Solr from Source -------------------------------------------------- - -1. Download the Java 11 JDK (Java Development Kit) or later from https://jdk.java.net/ - You will need the JDK installed, and the $JAVA_HOME/bin (Windows: %JAVA_HOME%\bin) - folder included on your command path. To test this, issue a "java -version" command - from your shell (command prompt) and verify that the Java version is 11 or later. - -2. Download the Apache Solr distribution, linked from the above web site. - Unzip the distribution to a folder of your choice, e.g. C:\solr or ~/solr - Alternately, you can obtain a copy of the latest Apache Solr source code - directly from the GIT repository: - - https://solr.apache.org/community.html#version-control - -3. Navigate to the root of your source tree folder and issue the `./gradlew tasks` - command to see the available options for building, testing, and packaging Solr. - - `./gradlew assemble` will create a Solr executable. - cd to "./solr/packaging/build/solr-9.0.0-SNAPSHOT" and run the bin/solr script - to start Solr. - - NOTE: `gradlew` is the "Gradle Wrapper" and will automatically download and - start using the correct version of Gradle. - - NOTE: `./gradlew help` will print a list of high-level tasks. There are also a - number of plain-text files in /help. - - NOTE: This CWiki page describes getting/building/testing Solr - in more detail: - `https://cwiki.apache.org/confluence/display/solr/HowToContribute` - -Export control -------------------------------------------------- -This distribution includes cryptographic software. The country in -which you currently reside may have restrictions on the import, -possession, use, and/or re-export to another country, of -encryption software. BEFORE using any encryption software, please -check your country's laws, regulations and policies concerning the -import, possession, or use, and re-export of encryption software, to -see if this is permitted. See for more -information. - -The U.S. Government Department of Commerce, Bureau of Industry and -Security (BIS), has classified this software as Export Commodity -Control Number (ECCN) 5D002.C.1, which includes information security -software using or performing cryptographic functions with asymmetric -algorithms. The form and manner of this Apache Software Foundation -distribution makes it eligible for export under the License Exception -ENC Technology Software Unrestricted (TSU) exception (see the BIS -Export Administration Regulations, Section 740.13) for both object -code and source code. - -The following provides more details on the included cryptographic -software: - -Apache Solr uses the Apache Tika which uses the Bouncy Castle generic encryption libraries for -extracting text content and metadata from encrypted PDF files. -See https://www.bouncycastle.org/ for more details on Bouncy Castle. diff --git a/solr/bin/solr b/solr/bin/solr index bfee9829acb..396ef7c94b6 100755 --- a/solr/bin/solr +++ b/solr/bin/solr @@ -394,7 +394,7 @@ function print_usage() { echo " -e Name of the example to run; available examples:" echo " cloud: SolrCloud example" echo " techproducts: Comprehensive example illustrating many of Solr's core capabilities" - echo " schemaless: Schema-less example" + echo " schemaless: Schema-less example (schema is inferred from data during indexing)" echo " films: Example of starting with _default configset and adding explicit fields dynamically" echo "" echo " -a Additional parameters to pass to the JVM when starting Solr, such as to setup" diff --git a/solr/bin/solr.cmd b/solr/bin/solr.cmd index e2b0c6ca133..d9dc9298294 100755 --- a/solr/bin/solr.cmd +++ b/solr/bin/solr.cmd @@ -370,7 +370,7 @@ goto done @echo -e example Name of the example to run; available examples: @echo cloud: SolrCloud example @echo techproducts: Comprehensive example illustrating many of Solr's core capabilities -@echo schemaless: Schema-less example +@echo schemaless: Schema-less example (schema is inferred from data during indexing) @echo films: Example of starting with _default configset and defining explicit fields dynamically @echo. @echo -a opts Additional parameters to pass to the JVM when starting Solr, such as to setup diff --git a/solr/packaging/README.txt b/solr/packaging/README.txt new file mode 100644 index 00000000000..d92997c1a25 --- /dev/null +++ b/solr/packaging/README.txt @@ -0,0 +1,85 @@ + 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. + +Welcome to the Apache Solr project! +----------------------------------- + +Solr is the popular, blazing fast open source search platform for all your +enterprise, e-commerce, and analytics needs, built on Apache Lucene. + +For a complete description of the Solr project, team composition, source +code repositories, and other details, please see the Solr web site at +https://solr.apache.org/solr + +How to Use +---------- + +To get started run + +``` + bin/solr -help +``` + +Solr includes a few examples to help you get started. For instance, if you want +to run the techproducts example, enter: + +``` + bin/solr start -e techproducts +``` + +For a more in-depth introduction, please check out the tutorials in the Solr Reference +Guide: https://solr.apache.org/guide/solr/latest/getting-started/solr-tutorial.html. + +Support +------- + +- Users Mailing List: https://solr.apache.org/community.html#mailing-lists-chat +- Slack: Solr Community Channel. Sign up at https://s.apache.org/solr-slack +- IRC: #solr on libera.chat: https://web.libera.chat/?channels=#solr + + + +Files included in an Apache Solr binary distribution +---------------------------------------------------- + +server/ + A self-contained Solr instance, complete with a sample + configuration and documents to index. Please see: bin/solr start -help + for more information about starting a Solr server. + +bin/ + Scripts to startup, manage and interact with Solr instances. + +example/ + Contains example documents and an alternative Solr home + directory containing various examples. + +modules/ + Contains modules to extend the functionality of Solr. + Libraries for these modules can be found under modules/*/lib + +prometheus-exporter/ + Contains a separate application to monitor Solr instances and export Prometheus metrics + +docker/ + Contains a Dockerfile to build a Docker image using the source or binary distribution. + `docker/scripts` contains scripts that the Docker image uses to manage Solr. + Refer to the README.md for instructions on how to build an image. + +docs/index.html + A link to the online version of Apache Solr Javadoc API documentation and Tutorial + +licenses/ + Licenses, notice files and signatures for Solr dependencies. diff --git a/solr/packaging/build.gradle b/solr/packaging/build.gradle index 91ce0b60c30..6b993add6a5 100644 --- a/solr/packaging/build.gradle +++ b/solr/packaging/build.gradle @@ -82,7 +82,10 @@ distributions { include "licenses/**" exclude "licenses/README.committers.txt" include "CHANGES.txt" - include "README.md" + }) + + from(projectDir, { + include "README.txt" }) from ('static/lib', { diff --git a/solr/solr-ref-guide/modules/getting-started/getting-started-nav.adoc b/solr/solr-ref-guide/modules/getting-started/getting-started-nav.adoc index c060317d227..e384f820703 100644 --- a/solr/solr-ref-guide/modules/getting-started/getting-started-nav.adoc +++ b/solr/solr-ref-guide/modules/getting-started/getting-started-nav.adoc @@ -26,6 +26,7 @@ ** xref:solr-glossary.adoc[] * xref:solr-tutorial.adoc[] +** xref:tutorial-five-minutes.adoc[] ** xref:tutorial-techproducts.adoc[] ** xref:tutorial-films.adoc[] ** xref:tutorial-diy.adoc[] diff --git a/solr/solr-ref-guide/modules/getting-started/pages/tutorial-films.adoc b/solr/solr-ref-guide/modules/getting-started/pages/tutorial-films.adoc index 384cf3c521e..049e753c692 100644 --- a/solr/solr-ref-guide/modules/getting-started/pages/tutorial-films.adoc +++ b/solr/solr-ref-guide/modules/getting-started/pages/tutorial-films.adoc @@ -1,4 +1,4 @@ -= Exercise 2 Index Films Data += Exercise 2: Index Films Data :experimental: // Licensed to the Apache Software Foundation (ASF) under one // or more contributor license agreements. See the NOTICE file diff --git a/solr/solr-ref-guide/modules/getting-started/pages/tutorial-five-minutes.adoc b/solr/solr-ref-guide/modules/getting-started/pages/tutorial-five-minutes.adoc new file mode 100644 index 00000000000..7b985fa0a39 --- /dev/null +++ b/solr/solr-ref-guide/modules/getting-started/pages/tutorial-five-minutes.adoc @@ -0,0 +1,153 @@ += Exercise 0: Five Minutes to Searching! +:experimental: +// 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. + +This exercise will walk you through how to start using Solr in just 5 Minutes! + +== Launch Solr in SolrCloud Mode +To launch Solr, run: `bin/solr start -c` on Unix or MacOS; `bin\solr.cmd start -c` on Windows. + +To start another Solr node and have it join the cluster alongside the first node, + +[source] +---- +bin/solr -c -z localhost:9983 -p 8984 +---- + + +== Create a collection + +Like a database system holds data in tables, Solr holds data in collections. A collection can be created as follows: + +[source] +---- +curl --request POST \ +--url http://localhost:8983/api/collections \ +--header 'Content-Type: application/json' \ +--data '{ + "create": { + "name": "techproducts", + "numShards": 1, + "replicationFactor": 1 + } +}' +---- + +== Define a schema + +Let us define some of the fields that our documents will contain. + +[source] +---- +curl --request POST \ + --url http://localhost:8983/api/collections/techproducts/schema \ + --header 'Content-Type: application/json' \ + --data '{ + "add-field": [ + {"name": "name", "type": "text_general", "multiValued": false}, + {"name": "cat", "type": "string", "multiValued": true}, + {"name": "manu", "type": "string"}, + {"name": "features", "type": "text_general", "multiValued": true}, + {"name": "weight", "type": "pfloat"}, + {"name": "price", "type": "pfloat"}, + {"name": "popularity", "type": "pint"}, + {"name": "inStock", "type": "boolean", "stored": true}, + {"name": "store", "type": "location"} + ] +}' +---- + +## Index some documents + +A single document can be indexed as: + +[source] +---- +curl --request POST \ +--url 'http://localhost:8983/api/collections/techproducts/update' \ + --header 'Content-Type: application/json' \ + --data ' { + "id" : "978-0641723445", + "cat" : ["book","hardcover"], + "name" : "The Lightning Thief", + "author" : "Rick Riordan", + "series_t" : "Percy Jackson and the Olympians", + "sequence_i" : 1, + "genre_s" : "fantasy", + "inStock" : true, + "price" : 12.50, + "pages_i" : 384 + }' +---- + +Multiple documents can be indexed in the same request: + +[source] +---- +curl --request POST \ + --url 'http://localhost:8983/api/collections/techproducts/update' \ + --header 'Content-Type: application/json' \ + --data ' [ + { + "id" : "978-0641723445", + "cat" : ["book","hardcover"], + "name" : "The Lightning Thief", + "author" : "Rick Riordan", + "series_t" : "Percy Jackson and the Olympians", + "sequence_i" : 1, + "genre_s" : "fantasy", + "inStock" : true, + "price" : 12.50, + "pages_i" : 384 + } +, + { + "id" : "978-1423103349", + "cat" : ["book","paperback"], + "name" : "The Sea of Monsters", + "author" : "Rick Riordan", + "series_t" : "Percy Jackson and the Olympians", + "sequence_i" : 2, + "genre_s" : "fantasy", + "inStock" : true, + "price" : 6.49, + "pages_i" : 304 + } +]' +---- + +A file containing the documents can be indexed as follows: + +[source] +---- +curl -H "Content-Type: application/json" \ + -X POST \ + -d @example/products.json \ + --url 'http://localhost:8983/api/collections/techproducts/update?commit=true' +---- + +== Commit the Changes +After documents are indexed into a collection, they are not immediately available for searching. In order to have them searchable, a commit operation (also called `refresh` in other search engines like OpenSearch etc.) is needed. Commits can be scheduled at periodic intervals using auto-commits as follows. + +[source] +---- +curl -X POST -H 'Content-type: application/json' -d '{"set-property":{"updateHandler.autoCommit.maxTime":15000}}' http://localhost:8983/api/collections/techproducts/config +---- + +== Make some Basic search queries +FIXME diff --git a/solr/solr-ref-guide/modules/getting-started/pages/tutorial-techproducts.adoc b/solr/solr-ref-guide/modules/getting-started/pages/tutorial-techproducts.adoc index ed2a4273cd9..9f634555b6a 100644 --- a/solr/solr-ref-guide/modules/getting-started/pages/tutorial-techproducts.adoc +++ b/solr/solr-ref-guide/modules/getting-started/pages/tutorial-techproducts.adoc @@ -1,4 +1,4 @@ -= Exercise 1 Index Techproducts Data += Exercise 1: Index Techproducts Data :experimental: // Licensed to the Apache Software Foundation (ASF) under one // or more contributor license agreements. See the NOTICE file