SOLR-15242: Consolidate README.md with solr/README.md (#610)

Consolidate the ./README.md and ./solr/README.md into a new top level README.md optimized for Github.  The /solr/README.adoc is now to help a developer understand what the subdirectories are all about.   Introduced a new README.txt in the ./solr/packaging directory to ship with the distributions.

Co-authored-by: [email protected] <>
Co-authored-by: Jan Høydahl <[email protected]>
Co-authored-by: Houston Putman <[email protected]>

Author: 3 people

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 <https://solr.apache.org/guide/solr>
-
-## 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-<version>.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 <EXAMPLE> where <EXAMPLE> 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.

dev-docs/FAQ.adoc

@@ -19,6 +19,32 @@ branch to avoid extra mailing list traffic etc.
 Periodically review https://github.com/apache/solr/branches/all to see if you have
 created a branch that can be deleted.
 
+=== Running Solr in Docker
+
+You can run Solr in Docker via the [official image](https://hub.docker.com/_/solr).
+
+To run Solr in a container and expose the Solr port, run:
+
+`docker run -p 8983:8983 solr`
+
+In order to start Solr in cloud mode, run the following.
+
+`docker run -p 8983:8983 solr solr-fg -c`
+
+For documentation on using the official docker builds, please refer to the [DockerHub page](https://hub.docker.com/_/solr).
+Up to date documentation for running locally built images of this branch can be found in the [local reference guide](solr/solr-ref-guide/src/running-solr-in-docker.adoc).
+
+There is also a gradle task for building custom Solr images from your local checkout.
+These local images are built identically to the official image except for retrieving the Solr artifacts locally instead of from the official release.
+This can be useful for testing out local changes as well as creating custom images for yourself or your organization.
+The task will output the image name to use at the end of the build.
+
+`./gradlew docker`
+
+For more info on building an image, run:
+
+`./gradlew helpDocker`
+
 === Whats the fastest build lifecycle for frontend work on Solr Admin?
 
 Run `gradle dev`, and then `cd ./packaging/build/dev/`.  Fire up your cluster

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:
+
+<https://solr.apache.org/community.html#version-control>
+
+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 <source folder root>/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`

solr/README.adoc

@@ -0,0 +1,68 @@
+////
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+////
+
+== Solr Source Directories
+
+link:benchmark/[]::
+Benchmarking module for Solr.
+
+link:bin/[]::
+Scripts to startup, manage and interact with Solr instances.
+
+link:core/[]::
+Base Solr code.
+
+link:distribution/[]::
+Gradle project for building a full release of Solr.
+
+link:docker/[]::
+Contains a Dockerfile to build a Docker image using the source or binary distribution.
+`docker/scripts` contains scripts that the Docker image uses to manage Solr.
+
+link:documentation/[]::
+Gradle project to build the JavaDocs site.
+
+link:example/[]::
+Contains example documents and an alternative Solr home
+directory containing various examples.
+
+link:license/[]::
+Licenses, notice files and signatures for Solr dependencies.
+
+link:modules/[]::
+Contains modules to extend the functionality of Solr.
+
+link:packaging/[]::
+Gradle project to build the binary release of Solr.
+
+link:prometheus-exporter/[]::
+Contains a separate application to monitor Solr instances and export Prometheus metrics.
+
+link:server/[]::
+Gradle project that builds the Jetty server to run Solr.
+
+link:solr-ref-guide/[]::
+The Solr Reference Guide source files including Java examples.
+
+link:solrj/[]::
+Solr client code for Java applications.
+
+link:test-framework/[]::
+Solr test framework for internal tests and external tests integrating Solr.
+
+link:webapp/[]::
+Admin UI Javascript and supporting assets.