Add docs for bundled jdk (#40487)

rjernst · jasontedor · commit d96e71d35e7a · 2019-03-29T09:04:46.000-04:00
This commit changes the note in docs about required java version to note
the existence of the bundled jdk and how to bring your own java. It also
reorganizes the zip/targz docs as zip is no longer suitable on
Linux/MacOS.
diff --git a/docs/reference/getting-started.asciidoc b/docs/reference/getting-started.asciidoc
@@ -114,34 +114,33 @@ https://www.elastic.co/cloud/elasticsearch-service/signup[Try out the
 Elasticsearch Service for free].
 ==============
 
-Elasticsearch requires at least Java 8. Specifically as of this writing, it is recommended that you use the Oracle JDK version {jdk}. Java installation varies from platform to platform so we won't go into those details here. Oracle's recommended installation documentation can be found on http://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html[Oracle's website]. Suffice to say, before you install Elasticsearch, please check your Java version first by running (and then install/upgrade accordingly if needed):
+NOTE: Elasticsearch includes a bundled version of http://openjdk.java.net[OpenJDK]
+from the JDK maintainers (GPLv2+CE). To use your own version of Java,
+see the <<jvm-version, JVM version requirements>>
 
-[source,sh]
---------------------------------------------------
-java -version
-echo $JAVA_HOME
---------------------------------------------------
-
-Once we have Java set up, we can then download and run Elasticsearch. The binaries are available from http://www.elastic.co/downloads[`www.elastic.co/downloads`] along with all the releases that have been made in the past. For each release, you have a choice among a `zip` or `tar` archive, a `DEB` or `RPM` package, or a Windows `MSI` installation package.
+The binaries are available from http://www.elastic.co/downloads[`www.elastic.co/downloads`]
+along with all the releases that have been made in the past. For each release, platform
+dependent archive versions are available for Windows, Linux and MacOS, as well as `DEB` and `RPM`
+packages for Linux, and `MSI` installation packages for Windows.
 
 [float]
-=== Installation example with tar
+=== Installation example on Linux
 
-For simplicity, let's use the {ref}/zip-targz.html[tar] file.
+For simplicity, let's use the {ref}/targz.html[tar] file.
 
-Let's download the Elasticsearch {version} tar as follows:
+Let's download the Elasticsearch {version} Linux tar as follows:
 
 ["source","sh",subs="attributes,callouts"]
 --------------------------------------------------
-curl -L -O https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}.tar.gz
+curl -L -O https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}-linux-x86_64.tar.gz
 --------------------------------------------------
 // NOTCONSOLE
 
 Then extract it as follows:
 
 ["source","sh",subs="attributes,callouts"]
 --------------------------------------------------
-tar -xvf elasticsearch-{version}.tar.gz
+tar -xvf elasticsearch-{version}-linux-x86_64.tar.gz
 --------------------------------------------------
 
 It will then create a bunch of files and folders in your current directory. We then go into the bin directory as follows:
@@ -172,7 +171,7 @@ Then double-click the downloaded file to launch the GUI. Within the first screen
 image::images/msi_installer/msi_installer_locations.png[]
 
 Then select whether to install as a service or start Elasticsearch manually as needed.
-To align with the tar example, choose not to install as a service:
+To align with the Linux example, choose not to install as a service:
 
 [[getting-started-msi-installer-service]]
 image::images/msi_installer/msi_installer_no_service.png[]
diff --git a/docs/reference/setup.asciidoc b/docs/reference/setup.asciidoc
@@ -23,20 +23,19 @@ platforms, but it is possible that it will work on other platforms too.
 [[jvm-version]]
 == Java (JVM) Version
 
-Elasticsearch is built using Java, and requires at least
-http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java {jdk_major}]
-in order to run. Only Oracle's Java and the OpenJDK are supported. The same JVM
-version should be used on all Elasticsearch nodes and clients.
-
-We recommend installing Java version *{jdk} or a later version in the Java
-{jdk_major} release series*. We recommend using a
-link:/support/matrix[supported]
+Elasticsearch is built using Java, and includes a bundled version of
+http://openjdk.java.net[OpenJDK] from the JDK maintainers (GPLv2+CE)
+within each distribution. The bundled JVM exists within the `jdk` directory of
+the Elasticsearch home directory.
+
+To use your own version of Java, set the `JAVA_HOME` environment variable.
+When using your own version, the bundled JVM directory may be removed.
+If not using the bundled JVM, we recommend installing Java version
+ *{jdk} or a later version in the Java {jdk_major} release series*. We recommend
+using a link:/support/matrix[supported]
 http://www.oracle.com/technetwork/java/eol-135779.html[LTS version of Java].
 Elasticsearch will refuse to start if a known-bad version of Java is used.
 
-The version of Java that Elasticsearch will use can be configured by setting
-the `JAVA_HOME` environment variable.
-
 --
 
 include::setup/install.asciidoc[]
diff --git a/docs/reference/setup/important-settings/error-file.asciidoc b/docs/reference/setup/important-settings/error-file.asciidoc
@@ -5,7 +5,7 @@ By default, Elasticsearch configures the JVM to write fatal error logs
 to the default logging directory (this is `/var/log/elasticsearch` for
 the <<rpm,RPM>> and <<deb,Debian>> package distributions, and the `logs`
 directory under the root of the Elasticsearch installation for the
-<<zip-targz,tar and zip>> archive distributions). These are logs
+<<targz,tar>> and <<zip-windows,zip>> archive distributions). These are logs
 produced by the JVM when it encounters a fatal error (e.g., a
 segmentation fault). If this path is not suitable for receiving logs,
 you should modify the entry `-XX:ErrorFile=...` in
diff --git a/docs/reference/setup/important-settings/heap-dump-path.asciidoc b/docs/reference/setup/important-settings/heap-dump-path.asciidoc
@@ -5,7 +5,7 @@ By default, Elasticsearch configures the JVM to dump the heap on out of
 memory exceptions to the default data directory (this is
 `/var/lib/elasticsearch` for the <<rpm,RPM>> and <<deb,Debian>> package
 distributions, and the `data` directory under the root of the
-Elasticsearch installation for the <<zip-targz,tar and zip>> archive
+Elasticsearch installation for the <<targz,tar>> and <<zip-windows,zip>> archive
 distributions). If this path is not suitable for receiving heap dumps,
 you should modify the entry `-XX:HeapDumpPath=...` in
 <<jvm-options,`jvm.options`>>. If you specify a directory, the JVM
diff --git a/docs/reference/setup/install.asciidoc b/docs/reference/setup/install.asciidoc
@@ -16,12 +16,17 @@ Elasticsearch Service for free].
 Elasticsearch is provided in the following package formats:
 
 [horizontal]
-`zip`/`tar.gz`::
+Linux and MacOS `tar.gz` archives::
 
-The `zip` and `tar.gz` packages are suitable for installation on any system
-and are the easiest choice for getting started with Elasticsearch on most systems.
+The `tar.gz` archives are available for installation on any Linux distribution and MacOS.
 +
-<<zip-targz>> or <<zip-windows>>
+<<targz>>
+
+Windows `.zip` archive::
+
+The `zip` archive is suitable for installation on Windows.
++
+<<zip-windows>>
 
 `deb`::
 
@@ -69,7 +74,7 @@ Chef::   https://github.com/elastic/cookbook-elasticsearch[cookbook-elasticsearc
 Ansible:: https://github.com/elastic/ansible-elasticsearch[ansible-elasticsearch]
 
 
-include::install/zip-targz.asciidoc[]
+include::install/targz.asciidoc[]
 
 include::install/zip-windows.asciidoc[]
 
diff --git a/docs/reference/setup/install/deb.asciidoc b/docs/reference/setup/install/deb.asciidoc
@@ -11,9 +11,9 @@ The latest stable version of Elasticsearch can be found on the
 link:/downloads/elasticsearch[Download Elasticsearch] page. Other versions can
 be found on the link:/downloads/past-releases[Past Releases page].
 
-NOTE: Elasticsearch requires Java 8 or later. Use the
-http://www.oracle.com/technetwork/java/javase/downloads/index.html[official Oracle distribution]
-or an open-source distribution such as http://openjdk.java.net[OpenJDK].
+NOTE: Elasticsearch includes a bundled version of http://openjdk.java.net[OpenJDK]
+from the JDK maintainers (GPLv2+CE). To use your own version of Java,
+see the <<jvm-version, JVM version requirements>>
 
 [[deb-key]]
 ==== Import the Elasticsearch PGP Key
diff --git a/docs/reference/setup/install/rpm.asciidoc b/docs/reference/setup/install/rpm.asciidoc
@@ -7,17 +7,17 @@ Elasticsearch on any RPM-based system such as OpenSuSE, SLES, Centos, Red Hat,
 and Oracle Enterprise.
 
 NOTE: RPM install is not supported on distributions with old versions of RPM,
-such as SLES 11 and CentOS 5.  Please see <<zip-targz>> instead.
+such as SLES 11 and CentOS 5.  Please see <<targz>> instead.
 
 include::license.asciidoc[]
 
 The latest stable version of Elasticsearch can be found on the
 link:/downloads/elasticsearch[Download Elasticsearch] page. Other versions can
 be found on the link:/downloads/past-releases[Past Releases page].
 
-NOTE: Elasticsearch requires Java 8 or later. Use the
-http://www.oracle.com/technetwork/java/javase/downloads/index.html[official Oracle distribution]
-or an open-source distribution such as http://openjdk.java.net[OpenJDK].
+NOTE: Elasticsearch includes a bundled version of http://openjdk.java.net[OpenJDK]
+from the JDK maintainers (GPLv2+CE). To use your own version of Java,
+see the <<jvm-version, JVM version requirements>>
 
 [[rpm-key]]
 ==== Import the Elasticsearch PGP Key
diff --git a/docs/reference/setup/install/targz-daemon.asciidoc b/docs/reference/setup/install/targz-daemon.asciidoc
diff --git a/docs/reference/setup/install/targz-start.asciidoc b/docs/reference/setup/install/targz-start.asciidoc
diff --git a/docs/reference/setup/install/targz.asciidoc b/docs/reference/setup/install/targz.asciidoc
@@ -1,9 +1,7 @@
-[[zip-targz]]
-=== Install Elasticsearch with `.zip` or `.tar.gz`
+[[targz]]
+=== Install Elasticsearch from archive on Linux or MacOS
 
-Elasticsearch is provided as a `.zip` and as a `.tar.gz` package.  These
-packages can be used to install Elasticsearch on any system and are the
-easiest package format to use when trying out Elasticsearch.
+Elasticsearch is as a `.tar.gz` archive for Linux and MacOS. 
 
 include::license.asciidoc[]
 
@@ -12,12 +10,12 @@ link:/downloads/elasticsearch[Download Elasticsearch] page.
 Other versions can be found on the
 link:/downloads/past-releases[Past Releases page].
 
-NOTE: Elasticsearch requires Java 8 or later. Use the
-http://www.oracle.com/technetwork/java/javase/downloads/index.html[official Oracle distribution]
-or an open-source distribution such as http://openjdk.java.net[OpenJDK].
+NOTE: Elasticsearch includes a bundled version of http://openjdk.java.net[OpenJDK]
+from the JDK maintainers (GPLv2+CE). To use your own version of Java,
+see the <<jvm-version, JVM version requirements>>
 
-[[install-zip]]
-==== Download and install the `.zip` package
+[[install-linux]]
+==== Download and install archive for Linux
 
 ifeval::["{release-state}"=="unreleased"]
 
@@ -27,30 +25,28 @@ endif::[]
 
 ifeval::["{release-state}"!="unreleased"]
 
-The `.zip` archive for Elasticsearch v{version} can be downloaded and installed as follows:
-
+The Linux archive for Elasticsearch v{version} can be downloaded and installed as follows:
 
 ["source","sh",subs="attributes"]
 --------------------------------------------
-wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}-windows-x86_64.zip
-wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}-windows-x86_64.zip.sha512
-shasum -a 512 -c elasticsearch-{version}-windows-x86_64.zip.sha512 <1>
-unzip elasticsearch-{version}-windows-x86_64.zip
+wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}-linux-x86_64.tar.gz
+wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}-linux-x86_64.tar.gz.sha512
+shasum -a 512 -c elasticsearch-{version}-linux-x86_64.tar.gz.sha512 <1>
+tar -xzf elasticsearch-{version}-linux-x86_64.tar.gz
 cd elasticsearch-{version}/ <2>
 --------------------------------------------
-<1> Compares the SHA of the downloaded `.zip` archive and the published checksum, which should output
-    `elasticsearch-{version}-windows-x86_64.zip: OK`.
+<1> Compares the SHA of the downloaded `.tar.gz` archive and the published checksum, which should output
+    `elasticsearch-{version}-linux-x86_64.tar.gz: OK`.
 <2> This directory is known as `$ES_HOME`.
 
-Alternatively, you can download the following package, which contains only 
-features that are available under the Apache 2.0 license: 
-https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-oss-{version}-windows-x86_64.zip
+Alternatively, you can download the following package, which includes only 
+Apache 2.0 licensed code: 
+https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-oss-{version}-linux-x86_64.tar.gz
 
 endif::[]
 
-
-[[install-targz]]
-==== Download and install the `.tar.gz` package
+[[install-macos]]
+==== Download and install archive for MacOS
 
 ifeval::["{release-state}"=="unreleased"]
 
@@ -60,47 +56,47 @@ endif::[]
 
 ifeval::["{release-state}"!="unreleased"]
 
-The `.tar.gz` archive for Elasticsearch v{version} can be downloaded and installed as follows:
+The MacOS archive for Elasticsearch v{version} can be downloaded and installed as follows:
 
 ["source","sh",subs="attributes"]
 --------------------------------------------
-wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}-linux-x86_64.tar.gz
-wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}-linux-x86_64.tar.gz.sha512
-shasum -a 512 -c elasticsearch-{version}-linux-x86_64.tar.gz.sha512 <1>
-tar -xzf elasticsearch-{version}-linux-x86_64.tar.gz
+wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}-darwin-x86_64.tar.gz
+wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}-darwin-x86_64.tar.gz.sha512
+shasum -a 512 -c elasticsearch-{version}-darwin-x86_64.tar.gz.sha512 <1>
+tar -xzf elasticsearch-{version}-darwin-x86_64.tar.gz
 cd elasticsearch-{version}/ <2>
 --------------------------------------------
 <1> Compares the SHA of the downloaded `.tar.gz` archive and the published checksum, which should output
-    `elasticsearch-{version}-linux-x86_64.tar.gz: OK`.
+    `elasticsearch-{version}-darwin-x86_64.tar.gz: OK`.
 <2> This directory is known as `$ES_HOME`.
 
 Alternatively, you can download the following package, which includes only 
 Apache 2.0 licensed code: 
-https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-oss-{version}-linux-x86_64.tar.gz
+https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-oss-{version}-darwin-x86_64.tar.gz
 
 endif::[]
 
 ifdef::include-xpack[]
-[[zip-targz-enable-indices]]
+[[targz-enable-indices]]
 ==== Enable automatic creation of {xpack} indices
 
 {xpack} will try to automatically create a number of indices within {es}.
 include::xpack-indices.asciidoc[]
 
 endif::include-xpack[]
 
-[[zip-targz-running]]
-include::zip-targz-start.asciidoc[]
+[[targz-running]]
+include::targz-start.asciidoc[]
 
 include::check-running.asciidoc[]
 
 Log printing to `stdout` can be disabled using the `-q` or `--quiet`
 option on the command line.
 
 [[setup-installation-daemon]]
-include::zip-targz-daemon.asciidoc[]
+include::targz-daemon.asciidoc[]
 
-[[zip-targz-configuring]]
+[[targz-configuring]]
 ==== Configuring Elasticsearch on the command line
 
 Elasticsearch loads its configuration from the `$ES_HOME/config/elasticsearch.yml`
@@ -119,10 +115,10 @@ TIP: Typically, any cluster-wide settings (like `cluster.name`) should be
 added to the `elasticsearch.yml` config file, while any node-specific settings
 such as `node.name` could be specified on the command line.
 
-[[zip-targz-layout]]
-==== Directory layout of `.zip` and `.tar.gz` archives
+[[targz-layout]]
+==== Directory layout of archives
 
-The `.zip` and `.tar.gz` packages are entirely self-contained. All files and
+The archive distributions are entirely self-contained. All files and
 directories are, by default, contained within `$ES_HOME` -- the directory
 created when unpacking the archive.
 
diff --git a/docs/reference/setup/install/windows.asciidoc b/docs/reference/setup/install/windows.asciidoc
@@ -17,9 +17,9 @@ link:/downloads/elasticsearch[Download Elasticsearch] page.
 Other versions can be found on the
 link:/downloads/past-releases[Past Releases page].
 
-NOTE: Elasticsearch requires Java 8 or later. Use the
-http://www.oracle.com/technetwork/java/javase/downloads/index.html[official Oracle distribution]
-or an open-source distribution such as http://openjdk.java.net[OpenJDK].
+NOTE: Elasticsearch includes a bundled version of http://openjdk.java.net[OpenJDK]
+from the JDK maintainers (GPLv2+CE). To use your own version of Java,
+see the <<jvm-version, JVM version requirements>>
 
 [[download-msi]]
 ==== Download the `.msi` package
diff --git a/docs/reference/setup/install/zip-windows.asciidoc b/docs/reference/setup/install/zip-windows.asciidoc
@@ -1,7 +1,7 @@
 [[zip-windows]]
 === Install Elasticsearch with `.zip` on Windows
 
-Elasticsearch can be installed on Windows using the `.zip` package.  This
+Elasticsearch can be installed on Windows using the Windows `.zip` archive.  This
 comes with a `elasticsearch-service.bat` command which will setup Elasticsearch to run as a
 service.
 
@@ -16,9 +16,9 @@ link:/downloads/elasticsearch[Download Elasticsearch] page.
 Other versions can be found on the
 link:/downloads/past-releases[Past Releases page].
 
-NOTE: Elasticsearch requires Java 8 or later. Use the
-http://www.oracle.com/technetwork/java/javase/downloads/index.html[official Oracle distribution]
-or an open-source distribution such as http://openjdk.java.net[OpenJDK].
+NOTE: Elasticsearch includes a bundled version of http://openjdk.java.net[OpenJDK]
+from the JDK maintainers (GPLv2+CE). To use your own version of Java,
+see the <<jvm-version, JVM version requirements>>
 
 [[install-windows]]
 ==== Download and install the `.zip` package
diff --git a/docs/reference/setup/starting.asciidoc b/docs/reference/setup/starting.asciidoc
@@ -11,10 +11,10 @@ If you installed {es} with a `.tar.gz` package, you can start {es} from the
 command line.  
 
 [float]
-include::install/zip-targz-start.asciidoc[]
+include::install/targz-start.asciidoc[]
 
 [float]
-include::install/zip-targz-daemon.asciidoc[]
+include::install/targz-daemon.asciidoc[]
 
 [float]
 [[start-zip]]
@@ -69,4 +69,4 @@ include::install/init-systemd.asciidoc[]
 include::install/rpm-init.asciidoc[]
 
 [float]
-include::install/systemd.asciidoc[]
+include::install/systemd.asciidoc[]
