From da173d31b2f81a281eb199c82a8aa73cfc7f08a1 Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" <> Date: Tue, 8 Feb 2022 14:27:22 +0100 Subject: [PATCH 01/31] strawperson version of potential new README.md at the top level, replacing the existing README.md and solr/README.md --- README_v2.md | 176 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 README_v2.md diff --git a/README_v2.md b/README_v2.md new file mode 100644 index 00000000000..6e86c58f1a4 --- /dev/null +++ b/README_v2.md @@ -0,0 +1,176 @@ + + +# Welcome to the Apache Solr project! +----------------------------------- + +Solr is the popular, blazing fast open source enterprise search platform +written in Java and using [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/ + +## Online Documentation + +This README file only contains basic instructions. For comprehensive documentation, +visit the [Solr Reference Guide](https://solr.apache.org/guide/). + +## Getting Started +FIXME maybe put the tutorial that Noble or Ishan wrote??? Then at the end put the examples? + +### 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: + FIXME the labels in the README do NOT match what is in the bin/solr start -help, and are better! + 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 SolrCloud example, enter: + +``` + bin/solr -e cloud +``` + +### 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` + +### 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. + +## Building Solr from Source +FIXME --> is this where we get JDK from?? What about OpenJDK? +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. + +Download the Apache Solr distribution, from http://solr.apache.org/. FIXME link?? +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: + + + +As of 9.0, 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 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 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. + +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. + +## Contributing + +Please review the [Contributing to Solr Guide](https://cwiki.apache.org/confluence/display/solr/HowToContribute) +for information on contributing. + +## Discussion and Support + +- [Mailing Lists](https://solr.apache.org/community.html#mailing-lists-chat) +- [Issue Tracker (JIRA)](https://issues.apache.org/jira/browse/SOLR) +- IRC: `#solr` and `#solr-dev` on freenode.net FIXME +- [Slack](https://solr.apache.org/community.html#slack) + +# 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 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. From 9cf87bd1637d77b16c822f34f96c3128a818b84e Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" <> Date: Tue, 8 Feb 2022 14:32:16 +0100 Subject: [PATCH 02/31] we appear to still be on freenode, not librera --- README_v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README_v2.md b/README_v2.md index 6e86c58f1a4..183f5da1aa7 100644 --- a/README_v2.md +++ b/README_v2.md @@ -144,7 +144,7 @@ for information on contributing. - [Mailing Lists](https://solr.apache.org/community.html#mailing-lists-chat) - [Issue Tracker (JIRA)](https://issues.apache.org/jira/browse/SOLR) -- IRC: `#solr` and `#solr-dev` on freenode.net FIXME +- IRC: `#solr` and `#solr-dev` on freenode.net - [Slack](https://solr.apache.org/community.html#slack) # Export control From b67ad390316544333fc418653fd26e785c2f23f3 Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" <> Date: Thu, 10 Feb 2022 19:34:21 +0100 Subject: [PATCH 03/31] we have moved to libera.chat --- README_v2.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README_v2.md b/README_v2.md index 183f5da1aa7..44a637f5ef9 100644 --- a/README_v2.md +++ b/README_v2.md @@ -144,11 +144,11 @@ for information on contributing. - [Mailing Lists](https://solr.apache.org/community.html#mailing-lists-chat) - [Issue Tracker (JIRA)](https://issues.apache.org/jira/browse/SOLR) -- IRC: `#solr` and `#solr-dev` on freenode.net +- IRC: `#solr` and `#solr-dev` on libera.chat - [Slack](https://solr.apache.org/community.html#slack) -# Export control -------------------------------------------------- +## 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 From 2a2a32a536279b7db2d604032822ce497f02af23 Mon Sep 17 00:00:00 2001 From: Eric Pugh Date: Thu, 10 Feb 2022 19:44:59 +0100 Subject: [PATCH 04/31] Update README_v2.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jan Høydahl --- README_v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README_v2.md b/README_v2.md index 44a637f5ef9..78ad1c9b255 100644 --- a/README_v2.md +++ b/README_v2.md @@ -97,7 +97,7 @@ directly from the Git repository: -As of 9.0, Solr uses [Gradle](https://gradle.org/) as the build +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. From 0911f87b4fca29b688a37be60beb110fd9864a22 Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" <> Date: Thu, 10 Feb 2022 19:48:11 +0100 Subject: [PATCH 05/31] updated to latest openjdk --- README_v2.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README_v2.md b/README_v2.md index 78ad1c9b255..d543229f809 100644 --- a/README_v2.md +++ b/README_v2.md @@ -84,8 +84,8 @@ Solr has official support for running on Kubernetes, in the official Docker imag Please refer to the [Solr Operator](https://solr.apache.org/operator) home for details, tutorials and instructions. ## Building Solr from Source -FIXME --> is this where we get JDK from?? What about OpenJDK? -Download the Java 11 JDK (Java Development Kit) or later from https://jdk.java.net/ +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. From dfa308979bd9043254ffddfd5ce1acefddb92f0f Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" <> Date: Thu, 10 Feb 2022 20:37:41 +0100 Subject: [PATCH 06/31] use consistent descriptions for examples across README and help output --- solr/bin/solr | 2 +- solr/bin/solr.cmd | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/solr/bin/solr b/solr/bin/solr index cfc6f3032c8..5b52bc26951 100755 --- a/solr/bin/solr +++ b/solr/bin/solr @@ -391,7 +391,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 From bd2952846f3b4d575e66732b8af559e683f52bd0 Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" <> Date: Thu, 10 Feb 2022 20:40:12 +0100 Subject: [PATCH 07/31] remove fixme --- README_v2.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README_v2.md b/README_v2.md index d543229f809..051bad29349 100644 --- a/README_v2.md +++ b/README_v2.md @@ -39,7 +39,6 @@ Solr includes a few examples to help you get started. To run a specific example, ``` bin/solr -e where is one of: - FIXME the labels in the README do NOT match what is in the bin/solr start -help, and are better! cloud: SolrCloud example techproducts: Comprehensive example illustrating many of Solr's core capabilities schemaless: Schema-less example (schema is inferred from data during indexing) From 687715144a61532a1ccce02ec42e15123d9248c0 Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" <> Date: Thu, 10 Feb 2022 21:32:27 +0100 Subject: [PATCH 08/31] experimenting with adding more detailed docs --- README_v2.md | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 132 insertions(+), 2 deletions(-) diff --git a/README_v2.md b/README_v2.md index 051bad29349..74ed8d02cf5 100644 --- a/README_v2.md +++ b/README_v2.md @@ -33,6 +33,136 @@ visit the [Solr Reference Guide](https://solr.apache.org/guide/). ## Getting Started FIXME maybe put the tutorial that Noble or Ishan wrote??? Then at the end put the examples? +### Starting Solr + +Start a Solr node in cluster mode (SolrCloud mode) + +``` +bin/solr -c +``` + +To start another Solr node and have it join the cluster alongside the first node, + +``` +bin/solr -c -z localhost:9983 -p 8984 +``` + +An instance of the cluster coordination service, i.e. Zookeeper, was started on port 9983 when the first node was started. To start Zookeeper separately, please refer to XXXX. + +### Creating a collection + +Like a database system holds data in tables, Solr holds data in collections. A collection can be created as follows: + +``` +curl --request POST \ +--url http://localhost:8983/api/collections \ +--header 'Content-Type: application/json' \ +--data '{ +"create": { + "name": "techproducts", + "numShards": 1, + "replicationFactor": 1 +} +}' +``` + +### Defining a schema + +Let us define some of the fields that our documents will contain. + +``` +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"} + ] +}' +``` + +### Indexing documents + +A single document can be indexed as: + +``` +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: +``` +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: +``` +curl -H "Content-Type: application/json" \ + -X POST \ + -d @example/products.json \ + --url 'http://localhost:8983/api/collections/techproducts/update?commit=true' +``` + +### Commit +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. + +``` +curl -X POST -H 'Content-type: application/json' -d '{"set-property":{"updateHandler.autoCommit.maxTime":15000}}' http://localhost:8983/api/collections/techproducts/config +``` + +### Basic search queries +FIXME + ### Solr Examples Solr includes a few examples to help you get started. To run a specific example, enter: @@ -45,10 +175,10 @@ Solr includes a few examples to help you get started. To run a specific example, films: Example of starting with _default configset and adding explicit fields dynamically ``` -For instance, if you want to run the SolrCloud example, enter: +For instance, if you want to run the techproducts example, enter: ``` - bin/solr -e cloud + bin/solr -e techproducts ``` ### Running Solr in Docker From 8426d43b8a9b39604a5d6998a234d81ade493b94 Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Sat, 9 Jul 2022 20:10:01 -0400 Subject: [PATCH 09/31] respond to comments --- README_v2.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README_v2.md b/README_v2.md index 74ed8d02cf5..70b411727a0 100644 --- a/README_v2.md +++ b/README_v2.md @@ -219,7 +219,7 @@ You will need the JDK installed, and the $JAVA_HOME/bin (Windows: %JAVA_HOME%\bi 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 http://solr.apache.org/. FIXME link?? +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: @@ -230,8 +230,8 @@ 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 assemble` will create a Solr executable. -cd to `./solr/packaging/build/solr-9.0.0-SNAPSHOT` and run the `bin/solr` script +`./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 @@ -253,6 +253,8 @@ 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. From cf224ad9bf7753d3c22db30fa44d51cf488c89bb Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Sat, 9 Jul 2022 20:18:44 -0400 Subject: [PATCH 10/31] tabs to spaces --- README_v2.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/README_v2.md b/README_v2.md index 70b411727a0..8943cc9b363 100644 --- a/README_v2.md +++ b/README_v2.md @@ -58,11 +58,11 @@ curl --request POST \ --url http://localhost:8983/api/collections \ --header 'Content-Type: application/json' \ --data '{ -"create": { - "name": "techproducts", - "numShards": 1, - "replicationFactor": 1 -} + "create": { + "name": "techproducts", + "numShards": 1, + "replicationFactor": 1 + } }' ``` @@ -75,17 +75,17 @@ 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"} - ] + "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"} + ] }' ``` From cf6e6e81a8044fa3994f02fdded951f2b11a056d Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Thu, 14 Jul 2022 12:40:07 -0400 Subject: [PATCH 11/31] skelaton --- README_v3.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 README_v3.md diff --git a/README_v3.md b/README_v3.md new file mode 100644 index 00000000000..4e7cdc2f3fe --- /dev/null +++ b/README_v3.md @@ -0,0 +1,47 @@ + + +# Welcome to the Apache Solr project! +----------------------------------- + +Text about the solr project. + +Key links + - Solr Website + - Ref Guide + - Slack Community (not the ASF one??) + - ? What else? + + +## Download + +## Running Solr + - link to install docs + - Solr on Docker + - Solr on Kubernetes + +## How to Use +- metnion the examples +- links to tutorials in Ref Guide +- links to the 5 min to Indexing and Querying Documents (tutorial) artifact in ref Guide + +## Get Involved + +## Building +- Links. + +## Export Control From 3024f20b561dbe3f9be059e18523c6d7c8f0ff82 Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Thu, 14 Jul 2022 13:13:57 -0400 Subject: [PATCH 12/31] bring in some links --- README_v3.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/README_v3.md b/README_v3.md index 4e7cdc2f3fe..89b5367eaa2 100644 --- a/README_v3.md +++ b/README_v3.md @@ -18,7 +18,9 @@ # Welcome to the Apache Solr project! ----------------------------------- -Text about the solr project. +Solr is the popular, blazing fast open source search platform for all your +enterprise, ecommerce, and analytics needs, +written in Java and using [Apache Lucene](https://lucene.apache.org/). Key links - Solr Website @@ -39,9 +41,23 @@ Key links - links to tutorials in Ref Guide - links to the 5 min to Indexing and Querying Documents (tutorial) artifact in ref Guide +## Support + +- [Mailing Lists](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] + + ## 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-dev` on (libera.chat)[https://web.libera.chat/?channels=#solr-dev] ## Building - Links. - -## Export Control From 160b000246a51ff64c339d0d29a01ba90270f55c Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Thu, 14 Jul 2022 13:49:55 -0400 Subject: [PATCH 13/31] a take of moving content to the dev-docs --- README_v3.md | 40 ++++++++++++++++++---- dev-docs/FAQ.adoc | 26 ++++++++++++++ dev-docs/README.adoc | 81 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 141 insertions(+), 6 deletions(-) diff --git a/README_v3.md b/README_v3.md index 89b5367eaa2..c671b1b4dda 100644 --- a/README_v3.md +++ b/README_v3.md @@ -31,13 +31,42 @@ Key links ## Download +Downloads for the Apache Solr distribution are available from https://solr.apache.org/downloads.html. + ## Running Solr - - link to install docs - - Solr on Docker - - Solr on Kubernetes + +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 + 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: + +``` + bin/solr -e techproducts +``` + +### Installing Solr + +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). +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. ## How to Use -- metnion the examples +- mention the examples - links to tutorials in Ref Guide - links to the 5 min to Indexing and Querying Documents (tutorial) artifact in ref Guide @@ -59,5 +88,4 @@ To get involved in the developer community: - [Issue Tracker (JIRA)](https://issues.apache.org/jira/browse/SOLR) - IRC: `#solr-dev` on (libera.chat)[https://web.libera.chat/?channels=#solr-dev] -## Building -- Links. +Learn more about developing Solr by reading through the developer docs in `./dev-docs` source tree. diff --git a/dev-docs/FAQ.adoc b/dev-docs/FAQ.adoc index 5d6b004972a..19a9a8c97d2 100644 --- a/dev-docs/FAQ.adoc +++ b/dev-docs/FAQ.adoc @@ -18,3 +18,29 @@ 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` 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` From b43af2e31dcabe5b1f045a83b6618e0a5514f839 Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Thu, 14 Jul 2022 14:00:58 -0400 Subject: [PATCH 14/31] finish firt draft content --- README_v3.md | 38 +++++++++++++++++++++----------------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/README_v3.md b/README_v3.md index c671b1b4dda..988a8ec104b 100644 --- a/README_v3.md +++ b/README_v3.md @@ -35,6 +35,22 @@ Downloads for the Apache Solr distribution are available from https://solr.apach ## Running Solr +### Installing Solr + +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). +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. + +### How to Use + Solr includes a few examples to help you get started. To run a specific example, enter: ``` @@ -51,24 +67,12 @@ For instance, if you want to run the techproducts example, enter: bin/solr -e techproducts ``` -### Installing Solr - -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. +There are a number of tutorials to follow. Start out with [5 Minutes to Indexing and Querying Solr](MOVE TUTORIAL TO REF GUIDE), +and then move to the ecommerce inspired [Tech Products](https://solr.apache.org/guide/solr/latest/getting-started/tutorial-techproducts.html) tutorial. Go deep into faceting your data with some [Film data](https://solr.apache.org/guide/solr/latest/getting-started/tutorial-films.html), as well as learn about dynamic schemas. The third tutorial is built around (Indexing Your Own Data)[https://solr.apache.org/guide/solr/latest/getting-started/tutorial-diy.html] so you develop some hands on experience with Solr. -### Running Solr in Docker - -You can run Solr in Docker via the [official image](https://hub.docker.com/_/solr). -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. +You can wrap your learning path by running through [Scaling with SolrCloud](https://solr.apache.org/guide/solr/latest/getting-started/tutorial-solrcloud.html), +and some practice deploying [Solr on Amazon AWS](https://solr.apache.org/guide/solr/latest/getting-started/tutorial-aws.html). -## How to Use -- mention the examples -- links to tutorials in Ref Guide -- links to the 5 min to Indexing and Querying Documents (tutorial) artifact in ref Guide ## Support @@ -88,4 +92,4 @@ To get involved in the developer community: - [Issue Tracker (JIRA)](https://issues.apache.org/jira/browse/SOLR) - 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` source tree. +Learn more about developing Solr by reading through the developer docs in [./dev-docs](./dev-docs) source tree. From f29970627710bc11f27c93a5633d8321616be5b1 Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Thu, 14 Jul 2022 14:04:04 -0400 Subject: [PATCH 15/31] darn you markdown formatting --- README_v3.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README_v3.md b/README_v3.md index 988a8ec104b..18d9a5a0abf 100644 --- a/README_v3.md +++ b/README_v3.md @@ -68,7 +68,7 @@ For instance, if you want to run the techproducts example, enter: ``` There are a number of tutorials to follow. Start out with [5 Minutes to Indexing and Querying Solr](MOVE TUTORIAL TO REF GUIDE), -and then move to the ecommerce inspired [Tech Products](https://solr.apache.org/guide/solr/latest/getting-started/tutorial-techproducts.html) tutorial. Go deep into faceting your data with some [Film data](https://solr.apache.org/guide/solr/latest/getting-started/tutorial-films.html), as well as learn about dynamic schemas. The third tutorial is built around (Indexing Your Own Data)[https://solr.apache.org/guide/solr/latest/getting-started/tutorial-diy.html] so you develop some hands on experience with Solr. +and then move to the ecommerce inspired [Tech Products](https://solr.apache.org/guide/solr/latest/getting-started/tutorial-techproducts.html) tutorial. Go deep into faceting your data with some [Film data](https://solr.apache.org/guide/solr/latest/getting-started/tutorial-films.html), as well as learn about dynamic schemas. The third tutorial is built around [Indexing Your Own Data](https://solr.apache.org/guide/solr/latest/getting-started/tutorial-diy.html) so you develop some hands on experience with Solr. You can wrap your learning path by running through [Scaling with SolrCloud](https://solr.apache.org/guide/solr/latest/getting-started/tutorial-solrcloud.html), and some practice deploying [Solr on Amazon AWS](https://solr.apache.org/guide/solr/latest/getting-started/tutorial-aws.html). @@ -76,9 +76,9 @@ and some practice deploying [Solr on Amazon AWS](https://solr.apache.org/guide/s ## Support -- [Mailing Lists](https://solr.apache.org/community.html#mailing-lists-chat) +- [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] +- IRC: `#solr` on [libera.chat](https://web.libera.chat/?channels=#solr) ## Get Involved @@ -90,6 +90,6 @@ 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-dev` on (libera.chat)[https://web.libera.chat/?channels=#solr-dev] +- 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. From 5825539cc92daa3d9f272c0e291d8662b79ecaca Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Thu, 14 Jul 2022 16:01:55 -0400 Subject: [PATCH 16/31] port light weight tutorial into ref guide --- .../pages/tutorial-five-minutes.adoc | 153 ++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 solr/solr-ref-guide/modules/getting-started/pages/tutorial-five-minutes.adoc 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..d64446deeea --- /dev/null +++ b/solr/solr-ref-guide/modules/getting-started/pages/tutorial-five-minutes.adoc @@ -0,0 +1,153 @@ += Exercise 0: Five Minutes to Search! +: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 From 36e2fdcc2041a42f6c4d910dbb21b8e25d1bd868 Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Thu, 14 Jul 2022 16:02:50 -0400 Subject: [PATCH 17/31] link in tutorial --- .../modules/getting-started/getting-started-nav.adoc | 1 + 1 file changed, 1 insertion(+) 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[] From 28bdc78c47783a5f9d4f27da964fd7974b2926ea Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Thu, 14 Jul 2022 16:03:16 -0400 Subject: [PATCH 18/31] better header --- .../modules/getting-started/pages/tutorial-films.adoc | 2 +- .../modules/getting-started/pages/tutorial-techproducts.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) 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-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 From a31f3019da00eb92993dc543225c1418a9548493 Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Thu, 14 Jul 2022 16:04:35 -0400 Subject: [PATCH 19/31] better titlte --- .../modules/getting-started/pages/tutorial-five-minutes.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index d64446deeea..7b985fa0a39 100644 --- 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 @@ -1,4 +1,4 @@ -= Exercise 0: Five Minutes to Search! += 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 From f9d6535575d7ac9c56334fd25114903b6678d2a2 Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Tue, 19 Jul 2022 12:54:21 -0400 Subject: [PATCH 20/31] README set up for inclusion in our distributions --- solr/README.md | 228 -------------------------------------- solr/packaging/README.txt | 89 +++++++++++++++ 2 files changed, 89 insertions(+), 228 deletions(-) delete mode 100644 solr/README.md create mode 100644 solr/packaging/README.txt 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/packaging/README.txt b/solr/packaging/README.txt new file mode 100644 index 00000000000..78185858f7a --- /dev/null +++ b/solr/packaging/README.txt @@ -0,0 +1,89 @@ + + +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 enter + +``` + 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 indepth 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. +``` From 950b5a38a114c3119a968613c818be9d58de03bf Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Tue, 19 Jul 2022 13:02:13 -0400 Subject: [PATCH 21/31] typo --- solr/packaging/README.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solr/packaging/README.txt b/solr/packaging/README.txt index 78185858f7a..b8fdb60dca5 100644 --- a/solr/packaging/README.txt +++ b/solr/packaging/README.txt @@ -41,7 +41,7 @@ to run the techproducts example, enter: bin/solr start -e techproducts ``` -For a more indepth introduction, please check out the tutorials in the Solr Reference +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 From 657c5c21032e5dd4785f2b668f3549b148c9b696 Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Tue, 19 Jul 2022 13:02:29 -0400 Subject: [PATCH 22/31] finalizing the top level readme --- README_v3.md | 29 +++++++++++------------------ 1 file changed, 11 insertions(+), 18 deletions(-) diff --git a/README_v3.md b/README_v3.md index 18d9a5a0abf..845f8c53b78 100644 --- a/README_v3.md +++ b/README_v3.md @@ -19,25 +19,21 @@ ----------------------------------- Solr is the popular, blazing fast open source search platform for all your -enterprise, ecommerce, and analytics needs, -written in Java and using [Apache Lucene](https://lucene.apache.org/). - -Key links - - Solr Website - - Ref Guide - - Slack Community (not the ASF one??) - - ? What else? +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 ## Download -Downloads for the Apache Solr distribution are available from https://solr.apache.org/downloads.html. +Downloads for Apache Solr distributions are available at https://solr.apache.org/downloads.html. ## Running Solr ### Installing Solr -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. +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 @@ -49,12 +45,12 @@ Learn more about [Solr in Docker](https://solr.apache.org/guide/solr/latest/depl 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. -### How to Use +## How to Use Solr includes a few examples to help you get started. To run a specific example, enter: ``` - bin/solr -e where is one of: + 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) @@ -64,14 +60,11 @@ Solr includes a few examples to help you get started. To run a specific example, For instance, if you want to run the techproducts example, enter: ``` - bin/solr -e techproducts + bin/solr start -e techproducts ``` -There are a number of tutorials to follow. Start out with [5 Minutes to Indexing and Querying Solr](MOVE TUTORIAL TO REF GUIDE), -and then move to the ecommerce inspired [Tech Products](https://solr.apache.org/guide/solr/latest/getting-started/tutorial-techproducts.html) tutorial. Go deep into faceting your data with some [Film data](https://solr.apache.org/guide/solr/latest/getting-started/tutorial-films.html), as well as learn about dynamic schemas. The third tutorial is built around [Indexing Your Own Data](https://solr.apache.org/guide/solr/latest/getting-started/tutorial-diy.html) so you develop some hands on experience with Solr. - -You can wrap your learning path by running through [Scaling with SolrCloud](https://solr.apache.org/guide/solr/latest/getting-started/tutorial-solrcloud.html), -and some practice deploying [Solr on Amazon AWS](https://solr.apache.org/guide/solr/latest/getting-started/tutorial-aws.html). +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 From 7bc921f00c24d272d8e74823ac7f65aa75b2a17a Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Tue, 19 Jul 2022 13:03:05 -0400 Subject: [PATCH 23/31] Revamp! --- README.md | 151 +++++++++++++++--------------------------------------- 1 file changed, 41 insertions(+), 110 deletions(-) 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. From 27d85c4492bd02da8862f8479fe07b186234d9a1 Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Tue, 19 Jul 2022 13:03:42 -0400 Subject: [PATCH 24/31] finalized our top level README --- README_v2.md | 307 --------------------------------------------------- README_v3.md | 88 --------------- 2 files changed, 395 deletions(-) delete mode 100644 README_v2.md delete mode 100644 README_v3.md diff --git a/README_v2.md b/README_v2.md deleted file mode 100644 index 8943cc9b363..00000000000 --- a/README_v2.md +++ /dev/null @@ -1,307 +0,0 @@ - - -# Welcome to the Apache Solr project! ------------------------------------ - -Solr is the popular, blazing fast open source enterprise search platform -written in Java and using [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/ - -## Online Documentation - -This README file only contains basic instructions. For comprehensive documentation, -visit the [Solr Reference Guide](https://solr.apache.org/guide/). - -## Getting Started -FIXME maybe put the tutorial that Noble or Ishan wrote??? Then at the end put the examples? - -### Starting Solr - -Start a Solr node in cluster mode (SolrCloud mode) - -``` -bin/solr -c -``` - -To start another Solr node and have it join the cluster alongside the first node, - -``` -bin/solr -c -z localhost:9983 -p 8984 -``` - -An instance of the cluster coordination service, i.e. Zookeeper, was started on port 9983 when the first node was started. To start Zookeeper separately, please refer to XXXX. - -### Creating a collection - -Like a database system holds data in tables, Solr holds data in collections. A collection can be created as follows: - -``` -curl --request POST \ ---url http://localhost:8983/api/collections \ ---header 'Content-Type: application/json' \ ---data '{ - "create": { - "name": "techproducts", - "numShards": 1, - "replicationFactor": 1 - } -}' -``` - -### Defining a schema - -Let us define some of the fields that our documents will contain. - -``` -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"} - ] -}' -``` - -### Indexing documents - -A single document can be indexed as: - -``` -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: -``` -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: -``` -curl -H "Content-Type: application/json" \ - -X POST \ - -d @example/products.json \ - --url 'http://localhost:8983/api/collections/techproducts/update?commit=true' -``` - -### Commit -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. - -``` -curl -X POST -H 'Content-type: application/json' -d '{"set-property":{"updateHandler.autoCommit.maxTime":15000}}' http://localhost:8983/api/collections/techproducts/config -``` - -### Basic search queries -FIXME - -### 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 - 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: - -``` - bin/solr -e techproducts -``` - -### 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` - -### 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. - -## 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. - -## Contributing - -Please review the [Contributing to Solr Guide](https://cwiki.apache.org/confluence/display/solr/HowToContribute) -for information on contributing. - -## Discussion and Support - -- [Mailing Lists](https://solr.apache.org/community.html#mailing-lists-chat) -- [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) - -## 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 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/README_v3.md b/README_v3.md deleted file mode 100644 index 845f8c53b78..00000000000 --- a/README_v3.md +++ /dev/null @@ -1,88 +0,0 @@ - - -# 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](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 - -## Download - -Downloads for Apache Solr distributions are available at https://solr.apache.org/downloads.html. - -## Running Solr - -### Installing Solr - -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). -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. - -## How to Use - -Solr includes a few examples to help you get started. To run a specific example, enter: - -``` - 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: - -``` - 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) - - -## 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-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. From a465efed6acc1be25601cab756618aa9317e3057 Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Tue, 19 Jul 2022 13:20:34 -0400 Subject: [PATCH 25/31] Provide developer information on sub directories. --- solr/README.adoc | 69 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 solr/README.adoc diff --git a/solr/README.adoc b/solr/README.adoc new file mode 100644 index 00000000000..440b9eacb19 --- /dev/null +++ b/solr/README.adoc @@ -0,0 +1,69 @@ + + +Solr Source Directories +---------------------------------------------------- + +[benchmark/](benchmark/):: +Benchmarking module for Solr. + +[bin/](bin/):: +Scripts to startup, manage and interact with Solr instances. + +[core/](core/):: +Base Solr code. + +[distribution/](distribution/):: +Gradle project for building a full release of Solr. + +[docker/](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. + +[documentation/](documentation/):: +Gradle project to build the JavaDocs site. + +[example/](example/):: +Contains example documents and an alternative Solr home +directory containing various examples. + +[license/](license/):: +Licenses, notice files and signatures for Solr dependencies. + +[modules/](modules/):: +Contains modules to extend the functionality of Solr. + +[packaging/](packaging/):: +Gradle project to build the binary release of Solr. + +[prometheus-exporter/](prometheus-exporter/):: +Contains a separate application to monitor Solr instances and export Prometheus metrics. + +[server/](server/):: +Gradle project that builds the Jetty server to run Solr. + +[solr-ref-guide/](solr-ref-guide/):: +The Solr Reference Guide source files including Java examples. + +[solrj/](solrj/):: +Solr client code for Java applications. + +[test-framework/](test-framework/):: +Solr test framework for internal tests and external tests integrating Solr. + +[webapp/](webapp/):: +Admin UI Javascript and supporting assets. From 4c35ef447ef0f1145fffd6bdf6fb8709e6e0fa41 Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Tue, 19 Jul 2022 13:22:38 -0400 Subject: [PATCH 26/31] comments are hard --- solr/README.adoc | 4 ++-- solr/packaging/README.txt | 2 -- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/solr/README.adoc b/solr/README.adoc index 440b9eacb19..5c33cd2adae 100644 --- a/solr/README.adoc +++ b/solr/README.adoc @@ -1,4 +1,4 @@ - +//// Solr Source Directories ---------------------------------------------------- diff --git a/solr/packaging/README.txt b/solr/packaging/README.txt index b8fdb60dca5..8677a3aecb9 100644 --- a/solr/packaging/README.txt +++ b/solr/packaging/README.txt @@ -1,4 +1,3 @@ - Welcome to the Apache Solr project! ----------------------------------- From e90cec19ffd888e5ac4a9996b80a4e28ac8c392a Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Tue, 19 Jul 2022 13:24:38 -0400 Subject: [PATCH 27/31] Update README.adoc --- solr/README.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/solr/README.adoc b/solr/README.adoc index 5c33cd2adae..a9a0a2ae91b 100644 --- a/solr/README.adoc +++ b/solr/README.adoc @@ -18,16 +18,16 @@ Solr Source Directories ---------------------------------------------------- -[benchmark/](benchmark/):: +[benchmark/](benchmark/):: \ Benchmarking module for Solr. -[bin/](bin/):: +[bin/](bin/):: \ Scripts to startup, manage and interact with Solr instances. -[core/](core/):: +[core/](core/):: \ Base Solr code. -[distribution/](distribution/):: +[distribution/](distribution/):: \ Gradle project for building a full release of Solr. [docker/](docker/):: From e79a432a836de187f6ae7512d1ef625f06c90b48 Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Tue, 19 Jul 2022 13:26:05 -0400 Subject: [PATCH 28/31] Update README.adoc --- solr/README.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/solr/README.adoc b/solr/README.adoc index a9a0a2ae91b..3371615e3e8 100644 --- a/solr/README.adoc +++ b/solr/README.adoc @@ -15,8 +15,7 @@ limitations under the License. //// -Solr Source Directories ----------------------------------------------------- +== Solr Source Directories [benchmark/](benchmark/):: \ Benchmarking module for Solr. From 67c3f0a523f86eaffd84112cca65eaa17d8fb54e Mon Sep 17 00:00:00 2001 From: "epugh@opensourceconnections.com" Date: Tue, 19 Jul 2022 13:30:04 -0400 Subject: [PATCH 29/31] fixing links --- solr/README.adoc | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/solr/README.adoc b/solr/README.adoc index 3371615e3e8..7a0130a8feb 100644 --- a/solr/README.adoc +++ b/solr/README.adoc @@ -17,52 +17,52 @@ == Solr Source Directories -[benchmark/](benchmark/):: \ +benchmark/[]:: Benchmarking module for Solr. -[bin/](bin/):: \ +bin/[]:: Scripts to startup, manage and interact with Solr instances. -[core/](core/):: \ +core/[]:: Base Solr code. -[distribution/](distribution/):: \ +distribution/[]:: Gradle project for building a full release of Solr. -[docker/](docker/):: +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. -[documentation/](documentation/):: +documentation/[]:: Gradle project to build the JavaDocs site. -[example/](example/):: +example/[]:: Contains example documents and an alternative Solr home directory containing various examples. -[license/](license/):: +license/[]:: Licenses, notice files and signatures for Solr dependencies. -[modules/](modules/):: +modules/[]:: Contains modules to extend the functionality of Solr. -[packaging/](packaging/):: +packaging/[]:: Gradle project to build the binary release of Solr. -[prometheus-exporter/](prometheus-exporter/):: +prometheus-exporter/[]:: Contains a separate application to monitor Solr instances and export Prometheus metrics. -[server/](server/):: +server/[]:: Gradle project that builds the Jetty server to run Solr. -[solr-ref-guide/](solr-ref-guide/):: +solr-ref-guide/[]:: The Solr Reference Guide source files including Java examples. -[solrj/](solrj/):: +solrj/[]:: Solr client code for Java applications. -[test-framework/](test-framework/):: +test-framework/[]:: Solr test framework for internal tests and external tests integrating Solr. -[webapp/](webapp/):: +webapp/[]:: Admin UI Javascript and supporting assets. From ee66008e7e163f09e6342d44a37c162dc986e40b Mon Sep 17 00:00:00 2001 From: Houston Putman Date: Tue, 19 Jul 2022 16:56:39 -0400 Subject: [PATCH 30/31] Fix links --- solr/README.adoc | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/solr/README.adoc b/solr/README.adoc index 7a0130a8feb..d1387439cd8 100644 --- a/solr/README.adoc +++ b/solr/README.adoc @@ -17,52 +17,52 @@ == Solr Source Directories -benchmark/[]:: +link:benchmark/[]:: Benchmarking module for Solr. -bin/[]:: +link:bin/[]:: Scripts to startup, manage and interact with Solr instances. -core/[]:: +link:core/[]:: Base Solr code. -distribution/[]:: +link:distribution/[]:: Gradle project for building a full release of Solr. -docker/[]:: +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. -documentation/[]:: +link:documentation/[]:: Gradle project to build the JavaDocs site. -example/[]:: +link:example/[]:: Contains example documents and an alternative Solr home directory containing various examples. -license/[]:: +link:license/[]:: Licenses, notice files and signatures for Solr dependencies. -modules/[]:: +link:modules/[]:: Contains modules to extend the functionality of Solr. -packaging/[]:: +link:packaging/[]:: Gradle project to build the binary release of Solr. -prometheus-exporter/[]:: +link:prometheus-exporter/[]:: Contains a separate application to monitor Solr instances and export Prometheus metrics. -server/[]:: +link:server/[]:: Gradle project that builds the Jetty server to run Solr. -solr-ref-guide/[]:: +link:solr-ref-guide/[]:: The Solr Reference Guide source files including Java examples. -solrj/[]:: +link:solrj/[]:: Solr client code for Java applications. -test-framework/[]:: +link:test-framework/[]:: Solr test framework for internal tests and external tests integrating Solr. -webapp/[]:: +link:webapp/[]:: Admin UI Javascript and supporting assets. From 7c93dae147556b5cb97f56d39da679f4f7926eea Mon Sep 17 00:00:00 2001 From: Houston Putman Date: Tue, 19 Jul 2022 17:00:56 -0400 Subject: [PATCH 31/31] Package new solr binary readme --- solr/packaging/README.txt | 4 +--- solr/packaging/build.gradle | 5 ++++- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/solr/packaging/README.txt b/solr/packaging/README.txt index 8677a3aecb9..d92997c1a25 100644 --- a/solr/packaging/README.txt +++ b/solr/packaging/README.txt @@ -26,7 +26,7 @@ https://solr.apache.org/solr How to Use ---------- -To get started enter +To get started run ``` bin/solr -help @@ -54,7 +54,6 @@ Support 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 @@ -84,4 +83,3 @@ docs/index.html 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', {