From d96e71d35e7accea12750a592fd1f44f64485fb5 Mon Sep 17 00:00:00 2001 From: Ryan Ernst Date: Fri, 29 Mar 2019 06:04:46 -0700 Subject: [PATCH] Add docs for bundled jdk (#40487) 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. --- docs/reference/getting-started.asciidoc | 27 +++-- docs/reference/setup.asciidoc | 19 ++-- .../important-settings/error-file.asciidoc | 2 +- .../heap-dump-path.asciidoc | 2 +- docs/reference/setup/install.asciidoc | 15 ++- docs/reference/setup/install/deb.asciidoc | 6 +- docs/reference/setup/install/rpm.asciidoc | 8 +- ...-daemon.asciidoc => targz-daemon.asciidoc} | 0 ...gz-start.asciidoc => targz-start.asciidoc} | 0 .../{zip-targz.asciidoc => targz.asciidoc} | 100 +++++++++--------- docs/reference/setup/install/windows.asciidoc | 6 +- .../setup/install/zip-windows.asciidoc | 8 +- docs/reference/setup/starting.asciidoc | 6 +- 13 files changed, 99 insertions(+), 100 deletions(-) rename docs/reference/setup/install/{zip-targz-daemon.asciidoc => targz-daemon.asciidoc} (100%) rename docs/reference/setup/install/{zip-targz-start.asciidoc => targz-start.asciidoc} (100%) rename docs/reference/setup/install/{zip-targz.asciidoc => targz.asciidoc} (74%) diff --git a/docs/reference/getting-started.asciidoc b/docs/reference/getting-started.asciidoc index 9e7571e03831..6e112559f877 100755 --- a/docs/reference/getting-started.asciidoc +++ b/docs/reference/getting-started.asciidoc @@ -114,26 +114,25 @@ 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 <> -[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 @@ -141,7 +140,7 @@ 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 index c5cc25471264..d54941ed6aad 100644 --- 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. +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. -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] +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 index d58a752ac28f..d78b0e24ec7a 100644 --- 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 <> and <> package distributions, and the `logs` directory under the root of the Elasticsearch installation for the -<> archive distributions). These are logs +<> and <> 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 index fb8c7ff35f0d..25f3fbcebcbf 100644 --- 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 <> and <> package distributions, and the `data` directory under the root of the -Elasticsearch installation for the <> archive +Elasticsearch installation for the <> and <> archive distributions). If this path is not suitable for receiving heap dumps, you should modify the entry `-XX:HeapDumpPath=...` in <>. If you specify a directory, the JVM diff --git a/docs/reference/setup/install.asciidoc b/docs/reference/setup/install.asciidoc index 26a207824af0..f5dd418155d5 100644 --- 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. + -<> or <> +<> + +Windows `.zip` archive:: + +The `zip` archive is suitable for installation on 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 index 97b476233893..192737581bd5 100644 --- 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 <> [[deb-key]] ==== Import the Elasticsearch PGP Key diff --git a/docs/reference/setup/install/rpm.asciidoc b/docs/reference/setup/install/rpm.asciidoc index a450e202b689..c6f5647d08e2 100644 --- a/docs/reference/setup/install/rpm.asciidoc +++ b/docs/reference/setup/install/rpm.asciidoc @@ -7,7 +7,7 @@ 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 <> instead. +such as SLES 11 and CentOS 5. Please see <> instead. include::license.asciidoc[] @@ -15,9 +15,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 <> [[rpm-key]] ==== Import the Elasticsearch PGP Key diff --git a/docs/reference/setup/install/zip-targz-daemon.asciidoc b/docs/reference/setup/install/targz-daemon.asciidoc similarity index 100% rename from docs/reference/setup/install/zip-targz-daemon.asciidoc rename to docs/reference/setup/install/targz-daemon.asciidoc diff --git a/docs/reference/setup/install/zip-targz-start.asciidoc b/docs/reference/setup/install/targz-start.asciidoc similarity index 100% rename from docs/reference/setup/install/zip-targz-start.asciidoc rename to docs/reference/setup/install/targz-start.asciidoc diff --git a/docs/reference/setup/install/zip-targz.asciidoc b/docs/reference/setup/install/targz.asciidoc similarity index 74% rename from docs/reference/setup/install/zip-targz.asciidoc rename to docs/reference/setup/install/targz.asciidoc index d53243810375..75c9fdb42188 100644 --- a/docs/reference/setup/install/zip-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 <> -[[install-zip]] -==== Download and install the `.zip` package +[[install-linux]] +==== Download and install archive for Linux ifeval::["{release-state}"=="unreleased"] @@ -27,40 +25,7 @@ endif::[] ifeval::["{release-state}"!="unreleased"] -The `.zip` 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 -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`. -<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 - -endif::[] - - -[[install-targz]] -==== Download and install the `.tar.gz` package - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of Elasticsearch has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -The `.tar.gz` 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"] -------------------------------------------- @@ -80,8 +45,39 @@ https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-oss-{version} endif::[] +[[install-macos]] +==== Download and install archive for MacOS + +ifeval::["{release-state}"=="unreleased"] + +Version {version} of Elasticsearch has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +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}-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}-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}-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}. @@ -89,8 +85,8 @@ 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[] @@ -98,9 +94,9 @@ 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 index 46aadbc34a9f..83d1251148c4 100644 --- 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 <> [[download-msi]] ==== Download the `.msi` package diff --git a/docs/reference/setup/install/zip-windows.asciidoc b/docs/reference/setup/install/zip-windows.asciidoc index 967b449bc972..efed4b613c54 100644 --- 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 <> [[install-windows]] ==== Download and install the `.zip` package diff --git a/docs/reference/setup/starting.asciidoc b/docs/reference/setup/starting.asciidoc index 6fab871e7c9c..4474c247361d 100644 --- 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[] \ No newline at end of file +include::install/systemd.asciidoc[]