Skip to content

Commit

Permalink
SOLR-15242: Consolidate README.md with solr/README.md (#610)
Browse files Browse the repository at this point in the history 
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]>
  • Loading branch information
@epugh @janhoy @HoustonPutman
3 people authored Jul 20, 2022
1 parent 6126179 commit a34f9c9
Show file tree
Hide file tree
Showing 13 changed files with 463 additions and 343 deletions.
151 changes: 41 additions & 110 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
26 changes: 26 additions & 0 deletions dev-docs/FAQ.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
81 changes: 81 additions & 0 deletions dev-docs/README.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`
68 changes: 68 additions & 0 deletions solr/README.adoc
View file
Original file line number Diff line number Diff line change
@@ -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.
Loading

0 comments on commit a34f9c9

Please sign in to comment.