lucene/solr/solr-ref-guide
Jason Gerlowski 5377742a62
SOLR-13985: Bind to localhost interface by default (#1154)
Prior to this commit, Solr's Jetty listened for connections on all
network interfaces. This commit changes it to only listen on localhost,
to prevent incautious administrators from accidentally exposing their
Solr deployment to the world.

Administrators who wish to override this behavior can set the
SOLR_JETTY_HOST property in their Solr include file
(solr.in.sh/solr.in.cmd) to "0.0.0.0" or some other value.

A version of this commit was previously reverted due to inconsistency
between SOLR_HOST and SOLR_JETTY_HOST.  This commit fixes this issue.
2020-01-13 09:42:30 -05:00
..
src SOLR-13985: Bind to localhost interface by default (#1154) 2020-01-13 09:42:30 -05:00
tools Use toLowerCase with an explicit locale in CheckLinksAndAnchors. 2019-12-03 13:01:43 +01:00
README.adoc SOLR-13782: Remove PDF Ref Guide build (#999) 2019-11-19 14:54:30 -07:00
build.xml SOLR-14146: Zookeeper version not resolved in RefGuide (#1119) 2019-12-24 23:06:27 +01:00
ivy.xml SOLR-13782: Remove PDF Ref Guide build (#999) 2019-11-19 14:54:30 -07:00

README.adoc

= Solr Ref Guide
// 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 is the source for the Solr Reference Guide.

Raw content is stored in Asciidoc (`.adoc`) formatted files in the `src/` directory.

== Prerequisites for Building
These files are processed with AsciiDoctor in 2 different ways:

* HTML version, using Jekyll:
** `Ruby` (v2.3 or higher)
** The following gems must be installed:
*** `jekyll`: v3.5, not v4.x.
Use `gem install jekyll --force --version 3.5.0` to force install of v3.5.0.
*** `jekyll-asciidoc`: v2.1 or higher; latest version (3.0.0) is fine.
Use `gem install jekyll-asciidoc` to install.
*** `slim`: v3.0 or higher; latest version (4.0.1) is fine.
Use `gem install slim` to install.
*** `tilt`: v1.0 or higher; latest version (2.0.10) is fine.
Use `gem install tilt` to install.
*** `concurrent-ruby`: v1.0 or higher; latest version (1.1.5) is fine.
Use `gem install concurrent-ruby` to install.


== Building the Guide
For details on building the ref guide, see `ant -p`.

There are currently four available targets:

* `ant default`: builds the HTML versions of the Solr Ref Guide.
* `ant build-site`: also builds the HTML version.
* `ant clean`: removes the `../build/solr-ref-guide` directory.

The output of all builds will be located in `../build/solr-ref-guide`.

== Key Directories
Key directories to be aware of:

* `src` - where all human edited `*.adoc` files related to the Guide live, as well as various configuration, theme, and template files.
* `tools` - custom Java code for parsing metadata in our `src/*.adoc` files to produce some `_data/` files for site navigation purposes.
* `../build/solr-ref-guide/content` - a copy of the `src` dir generated by ant where:
** `*.template` files are processed to replace ant properties with their runtime values
** some `../build/solr-ref-guide/content/_data` files are generated by our java tools based header attributes from each of the `*.adoc` files
* `../build/solr-ref-guide/html-site` - HTML generated version of the ref guide

See the additional documentation in `src/metadocs` for more information about how to edit files, build for releases, or modifying any Jekyll templates.