OpenSearch/docs/reference/setup.asciidoc

[[setup]]
= Setup Elasticsearch

[partintro]
--
This section includes information on how to setup Elasticsearch and get it
running, including:

* Downloading
* Installing
* Starting
* Configuring

[[supported-platforms]]
[float]
== Supported platforms

The matrix of officially supported operating systems and JVMs is available here:
link:/support/matrix[Support Matrix].  Elasticsearch is tested on the listed
platforms, but it is possible that it will work on other platforms too.

[float]
[[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 8] 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 later*. 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.

NOTE: Elasticsearch ships with default configuration for running Elasticsearch on 64-bit server JVMs. If you are using a 32-bit client JVM,
you must remove `-server` from <<jvm-options,jvm.options>> and if you are using any 32-bit JVM you should reconfigure the thread stack size
from `-Xss1m` to `-Xss320k`.

--

include::setup/install.asciidoc[]

include::setup/configuration.asciidoc[]

include::setup/important-settings.asciidoc[]

include::setup/bootstrap-checks.asciidoc[]

include::setup/sysconfig.asciidoc[]

include::setup/upgrade.asciidoc[]

include::setup/stopping.asciidoc[]
Migrated documentation into the main repo 2013-08-28 19:24:34 -04:00			`[[setup]]`
Docs: Complete rewrite of setup, installation, and configuration docs 2016-04-03 10:09:24 -04:00			`= Setup Elasticsearch`
Migrated documentation into the main repo 2013-08-28 19:24:34 -04:00
			`[partintro]`
			`--`
Docs: Complete rewrite of setup, installation, and configuration docs 2016-04-03 10:09:24 -04:00			`This section includes information on how to setup Elasticsearch and get it`
			`running, including:`
Migrated documentation into the main repo 2013-08-28 19:24:34 -04:00
Docs: Complete rewrite of setup, installation, and configuration docs 2016-04-03 10:09:24 -04:00			`* Downloading`
			`* Installing`
			`* Starting`
			`* Configuring`
[DOCS] Make apt/yum repos more visible 2014-02-06 11:01:58 -05:00
Update setup.asciidoc Added link to the support matrix to Setup docs 2015-10-09 06:27:05 -04:00			`[[supported-platforms]]`
			`[float]`
			`== Supported platforms`

			`The matrix of officially supported operating systems and JVMs is available here:`
			`link:/support/matrix[Support Matrix]. Elasticsearch is tested on the listed`
			`platforms, but it is possible that it will work on other platforms too.`

Docs: Added recommended Java versions to the docs 2014-09-11 05:13:19 -04:00			`[float]`
			`[[jvm-version]]`
Docs: Complete rewrite of setup, installation, and configuration docs 2016-04-03 10:09:24 -04:00			`== Java (JVM) Version`
Docs: Added recommended Java versions to the docs 2014-09-11 05:13:19 -04:00
			`Elasticsearch is built using Java, and requires at least`
Docs: Removed references to java 7 and debian wheezy Related to #13694 2015-09-22 08:23:30 -04:00			`http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java 8] in`
Docs: Elasticsearch will refuse to start with a known bad JVM 2014-09-11 05:15:42 -04:00			`order to run. Only Oracle's Java and the OpenJDK are supported. The same JVM`
Update setup.asciidoc Add a note about using the same JVM version on all nodes and clients 2014-12-30 11:40:19 -05:00			`version should be used on all Elasticsearch nodes and clients.`
Docs: Added recommended Java versions to the docs 2014-09-11 05:13:19 -04:00
Docs: Complete rewrite of setup, installation, and configuration docs 2016-04-03 10:09:24 -04:00			`We recommend installing Java version {jdk} or later. Elasticsearch will`
			`refuse to start if a known-bad version of Java is used.`
Docs: Added recommended Java versions to the docs 2014-09-11 05:13:19 -04:00
Docs: Complete rewrite of setup, installation, and configuration docs 2016-04-03 10:09:24 -04:00			`The version of Java that Elasticsearch will use can be configured by setting`
			the `JAVA_HOME` environment variable.
Docs: Added recommended Java versions to the docs 2014-09-11 05:13:19 -04:00
Improve the out-of-the-box experience Elasticsearch can be run in a few different ways: - from the command line on Linux and Windows - as a service on Linux and Windows on both 32-bit client and 64-bit server VMs. We strive for a great out-of-the-box experience any of these combinations but today it is lacking on 32-bit client JVMs and on the Windows service. There are two deficiencies that arise: - on any 32-bit client JVM we fail to start out of the box because we force the server JVM in jvm.options - when installing the Windows service, the thread stack size must be specified in jvm.options This commit attempts to address these deficiencies. We should continue to force the server JVM because there are systems where the server JVM is not active by default (e.g., the 32-bit JDK on Windows). This does mean that if a user tries to run with a client JVM they will see a failure message at startup but this is the best that we can do if we want to continue to force the server JVM. Thus, this commit at least documents this situation. To improve the situation with installing the Windows service, this commit adds a default setting for the thread stack size. This default is chosen based on the default thread stack size across all 64-bit server JVMs. This means that if a user tries to run with a 32-bit JVM they could otherwise see significantly higher memory usage (this situation is complicated, it's really only on Windows where the extra memory usage is egregious, but cutting into the 32-bit address space on any system is bad). So this commit makes it so that the out-of-the-box experience is improved for the Windows service on 64-bit server JVMs and we document the need to adjust this setting on 32-bit JVMs. Again, we are focusing on the out-of-the-box experience here and this means optimizing for the best experience on any 64-bit server JVM as this covers the vast majority of the user base. The users that are on 32-bit JVMs will suffer a little bit but at least now any user on any 64-bit server JVM can start Elasticsearch out of the box. Finally, we fix some references to the jvm.options documentation. Relates #21920 2016-12-01 17:26:29 -05:00			`NOTE: Elasticsearch ships with default configuration for running Elasticsearch on 64-bit server JVMs. If you are using a 32-bit client JVM,`
			you must remove `-server` from <<jvm-options,jvm.options>> and if you are using any 32-bit JVM you should reconfigure the thread stack size
			from `-Xss1m` to `-Xss320k`.

Migrated documentation into the main repo 2013-08-28 19:24:34 -04:00			`--`

Docs: Complete rewrite of setup, installation, and configuration docs 2016-04-03 10:09:24 -04:00			`include::setup/install.asciidoc[]`
Migrated documentation into the main repo 2013-08-28 19:24:34 -04:00
Docs: Complete rewrite of setup, installation, and configuration docs 2016-04-03 10:09:24 -04:00			`include::setup/configuration.asciidoc[]`
add docs on new service.bat facility 2013-09-23 11:24:31 -04:00
Docs: Complete rewrite of setup, installation, and configuration docs 2016-04-03 10:09:24 -04:00			`include::setup/important-settings.asciidoc[]`
Migrated documentation into the main repo 2013-08-28 19:24:34 -04:00
Add bootstrap check docs This commit adds documentation for the bootstrap checks and provides either links or inline guidance for setting the necessary settings to pass the bootstrap checks. Relates #18605 2016-05-27 06:03:35 -04:00			`include::setup/bootstrap-checks.asciidoc[]`

Docs: Complete rewrite of setup, installation, and configuration docs 2016-04-03 10:09:24 -04:00			`include::setup/sysconfig.asciidoc[]`
Author: Sean Gallagher Date: Tue Apr 1 12:28:00 2014 Added upgrade.asciidoc and links to it from setup.asciidoc Author: Sean Gallagher Date: Apr 1 2014 Added upgrade.asciidoc Add upgrade instructions Author: Sean Gallagher Date: 4/4/14 Closes issue #5651 Fixed upgrade.asciidoc typo and incorrect usage. Author: Sean Gallagher Date: 4 Apr 2014 Closes 5651 2014-04-01 12:28:08 -04:00
			`include::setup/upgrade.asciidoc[]`
Die with dignity Today when a thread encounters a fatal unrecoverable error that threatens the stability of the JVM, Elasticsearch marches on. This includes out of memory errors, stack overflow errors and other errors that leave the JVM in a questionable state. Instead, the Elasticsearch JVM should die when these errors are encountered. This commit causes this to be the case. Relates #19272 2016-07-07 14:44:03 -04:00
			`include::setup/stopping.asciidoc[]`