From 7b740b4ea3dae634e0919d5420baf354b5d2c4de Mon Sep 17 00:00:00 2001
From: debadair <debadair@elastic.co>
Date: Thu, 20 Jun 2019 07:49:50 -0700
Subject: [PATCH] [DOCS] Add brew install instructions. Closes #42914 (#42915)

---
 docs/reference/getting-started.asciidoc    |  9 +--
 docs/reference/setup/install.asciidoc      |  8 +++
 docs/reference/setup/install/brew.asciidoc | 69 ++++++++++++++++++++++
 3 files changed, 82 insertions(+), 4 deletions(-)
 create mode 100644 docs/reference/setup/install/brew.asciidoc

diff --git a/docs/reference/getting-started.asciidoc b/docs/reference/getting-started.asciidoc
index eef66544d1b..5b802ad8577 100755
--- a/docs/reference/getting-started.asciidoc
+++ b/docs/reference/getting-started.asciidoc
@@ -118,10 +118,11 @@ NOTE: Elasticsearch includes a bundled version of http://openjdk.java.net[OpenJD
 from the JDK maintainers (GPLv2+CE). To use your own version of Java,
 see the <<jvm-version, JVM version requirements>>
 
-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.
+The binaries are available from http://www.elastic.co/downloads[`www.elastic.co/downloads`].
+Platform dependent archives are available for Windows, Linux and macOS. In addition,
+`DEB` and `RPM` packages are available for Linux, and an `MSI` installation package
+is available for Windows. You can also use the Elastic Homebrew tap to <<brew,install
+using the brew package manager>> on macOS.
 
 [float]
 === Installation example on Linux
diff --git a/docs/reference/setup/install.asciidoc b/docs/reference/setup/install.asciidoc
index 800cecb4065..7e03ad3947b 100644
--- a/docs/reference/setup/install.asciidoc
+++ b/docs/reference/setup/install.asciidoc
@@ -59,6 +59,13 @@ downloaded from the Elastic Docker Registry.
 +
 {ref}/docker.html[Install {es} with Docker]
 
+`brew`::
+
+Formulae are available from the Elastic Homebrew tap for installing
+{es} on macOS with the Homebrew package manager.
++
+{ref}/brew.html[Install {es} on macOS with Homebrew]
+
 [float]
 [[config-mgmt-tools]]
 === Configuration Management Tools
@@ -84,3 +91,4 @@ include::install/windows.asciidoc[]
 
 include::install/docker.asciidoc[]
 
+include::install/brew.asciidoc[]
diff --git a/docs/reference/setup/install/brew.asciidoc b/docs/reference/setup/install/brew.asciidoc
new file mode 100644
index 00000000000..f91ebbbbe14
--- /dev/null
+++ b/docs/reference/setup/install/brew.asciidoc
@@ -0,0 +1,69 @@
+[[brew]]
+=== Install {es} on macOS with Homebrew
+
+Elastic publishes Homebrew formulae so you can install {es} with the
+https://brew.sh/[Homebrew] package manager.
+
+To install with Homebrew, you first need to tap the
+Elastic Homebrew repository:
+
+[source,sh]
+-------------------------
+brew tap elastic/tap
+-------------------------
+
+Once you've tapped the Elastic Homebrew repo, you can use `brew install` to
+install the default distribution of {es}:
+
+[source,sh]
+-------------------------
+brew install elastic/tap/elasticsearch-full
+-------------------------
+
+This installs the most recently released default distribution of {es}.
+To install the OSS distribution, specify `elastic/tap/elasticsearch-oss`.
+
+[[brew-layout]]
+==== Directory layout for Homebrew installs
+
+When you install {es} with `brew install` the config files, logs,
+and data directory are stored in the following locations.
+
+[cols="<h,<,<m,<m",options="header",]
+|=======================================================================
+| Type | Description | Default Location | Setting
+| home
+  | Elasticsearch home directory or `$ES_HOME`
+  | /usr/local/var/homebrew/linked/elasticsearch
+ d|
+
+| bin
+  | Binary scripts including `elasticsearch` to start a node
+    and `elasticsearch-plugin` to install plugins
+  | /usr/local/var/homebrew/linked/elasticsearch/bin
+ d|
+
+| conf
+  | Configuration files including `elasticsearch.yml`
+  | /usr/local/etc/elasticsearch
+  | <<config-files-location,ES_PATH_CONF>>
+
+| data
+  | The location of the data files of each index / shard allocated
+    on the node. Can hold multiple locations.
+  | /usr/local/var/lib/elasticsearch
+  | path.data
+
+| logs
+  | Log files location.
+  | /usr/local/var/log/elasticsearch
+  | path.logs
+
+| plugins
+  | Plugin files location. Each plugin will be contained in a subdirectory.
+  | /usr/local/var/homebrew/linked/elasticsearch/plugins
+  |
+
+|=======================================================================
+
+include::next-steps.asciidoc[]