Add docs for Docker images

filebeat/docs/getting-started.asciidoc

@@ -27,17 +27,7 @@ After installing the Elastic Stack, read the following topics to learn how to in
 Before running Filebeat, you need to install and configure the Elastic stack. See
 {libbeat}/getting-started.html[Getting Started with Beats and the Elastic Stack].
 
-To download and install Filebeat, use the commands that work with your system
-(<<deb, deb>> for Debian/Ubuntu, <<rpm, rpm>> for Redhat/Centos/Fedora, <<mac,
-mac>> for OS X, and <<win, win>> for Windows).
-
-[NOTE]
-==================================================
-If you use Apt or Yum, you can <<setup-repositories,install Filebeat from our repositories>> to update to the newest version more easily.
-
-See our https://www.elastic.co/downloads/beats/filebeat[download page] for other installation options, such as 32-bit images.
-
-==================================================
+include::../../libbeat/docs/shared-download-and-install.asciidoc[]
 
 [[deb]]
 *deb:*
@@ -96,6 +86,24 @@ tar xzvf filebeat-{version}-darwin-x86_64.tar.gz
 
 endif::[]
 
+[[docker]]
+*docker:*
+
+ifeval::["{release-state}"=="unreleased"]
+
+Version {stack-version} of {beatname_uc} has not yet been released.
+
+endif::[]
+
+ifeval::["{release-state}"!="unreleased"]
+
+["source", "shell", subs="attributes"]
+------------------------------------------------
+docker pull {dockerimage}
+------------------------------------------------
+
+endif::[]
+
 [[win]]
 *win:*
 
@@ -137,17 +145,9 @@ started experience for common log formats. See <<filebeat-modules-quickstart>>
 to learn how to get started with modules. If you use Filebeat modules to get
 started, you can skip the content in this section, including the remaining
 getting started steps, and go directly to the <<filebeat-modules-quickstart>>
-page. 
+page.
 
-To configure Filebeat manually, you edit the configuration file. For rpm and deb,
-you'll find the configuration file at `/etc/filebeat/filebeat.yml`. For mac and
-win, look in the archive that you just extracted. There’s also a full example
-configuration file called `filebeat.full.yml` that shows all non-deprecated
-options.
-
-See the
-{libbeat}/config-file-format.html[Config File Format] section of the
-_Beats Platform Reference_ for more about the structure of the config file.
+include::../../libbeat/docs/shared-configuring.asciidoc[]
 
 Here is a sample of the `filebeat` section of the `filebeat.yml` file. Filebeat uses predefined
 default values for most configuration options.
@@ -240,6 +240,13 @@ sudo /etc/init.d/filebeat start
 sudo /etc/init.d/filebeat start
 ----------------------------------------------------------------------
 
+*docker:*
+
+["source", "shell", subs="attributes"]
+----------------------------------------------------------------------
+docker run {dockerimage}
+----------------------------------------------------------------------
+
 *mac:*
 
 [source,shell]

filebeat/docs/index.asciidoc

@@ -16,6 +16,7 @@ include::../../libbeat/docs/version.asciidoc[]
 :beatname_lc: filebeat
 :beatname_uc: Filebeat
 :security: X-Pack Security
+:dockerimage: docker.elastic.co/beats/{beatname_lc}:{version}
 
 include::./overview.asciidoc[]
 
@@ -31,6 +32,8 @@ include::../../libbeat/docs/shared-directory-layout.asciidoc[]
 
 include::../../libbeat/docs/repositories.asciidoc[]
 
+include::./running-on-docker.asciidoc[]
+
 include::./upgrading.asciidoc[]
 
 include::./how-filebeat-works.asciidoc[]

filebeat/docs/running-on-docker.asciidoc

@@ -0,0 +1 @@
+include::../../libbeat/docs/shared-docker.asciidoc[]

heartbeat/docs/getting-started.asciidoc

@@ -32,17 +32,7 @@ monitor are running.
 
 //TODO: Add a separate topic that explores deployment scenarios in more detail (like installing on a sub-network where there's a firewall etc.
 
-To download and install Heartbeat, use the commands that work with your
-system (<<deb, deb>> for Debian/Ubuntu, <<rpm, rpm>> for Redhat/Centos/Fedora,
-<<mac,mac>> for OS X, and <<win, win>> for Windows).
-
-[NOTE]
-==================================================
-If you use Apt or Yum, you can <<setup-repositories,install Heartbeat from our repositories>> to update to the newest version more easily.
-
-See our https://www.elastic.co/downloads/beats/heartbeat[download page] for other installation options, such as 32-bit images.
-
-==================================================
+include::../../libbeat/docs/shared-download-and-install.asciidoc[]
 
 [[deb]]
 *deb:*
@@ -101,6 +91,25 @@ tar xzvf heartbeat-{version}-darwin-x86_64.tar.gz
 
 endif::[]
 
+
+[[docker]]
+*docker:*
+
+ifeval::["{release-state}"=="unreleased"]
+
+Version {stack-version} of {beatname_uc} has not yet been released.
+
+endif::[]
+
+ifeval::["{release-state}"!="unreleased"]
+
+["source", "shell", subs="attributes"]
+------------------------------------------------
+docker pull {dockerimage}
+------------------------------------------------
+
+endif::[]
+
 [[win]]
 *win:*
 
@@ -147,15 +156,7 @@ options, see <<heartbeat-configuration-details>>.
 [[heartbeat-configuration]]
 === Step 2: Configuring Heartbeat
 
-To configure Heartbeat, you edit the configuration file. For rpm and deb,
-you'll find the configuration file at +/etc/heartbeat/heartbeat.yml+.
-For mac and win, look in the archive that you just extracted. There’s also a
-full example configuration file called `heartbeat.full.yml` that shows all
-non-deprecated options.
-
-See the
-{libbeat}/config-file-format.html[Config File Format] section of the
-_Beats Platform Reference_ for more about the structure of the config file.
+include::../../libbeat/docs/shared-configuring.asciidoc[]
 
 Heartbeat provides monitors to check the status of hosts at set intervals.
 You configure each monitor individually. Heartbeat currently provides monitors

heartbeat/docs/index.asciidoc

@@ -16,6 +16,7 @@ include::../../libbeat/docs/version.asciidoc[]
 :beatname_lc: heartbeat
 :beatname_uc: Heartbeat
 :security: X-Pack Security
+:dockerimage: docker.elastic.co/beats/{beatname_lc}:{version}
 
 include::./overview.asciidoc[]
 
@@ -29,6 +30,8 @@ include::../../libbeat/docs/shared-directory-layout.asciidoc[]
 
 include::../../libbeat/docs/repositories.asciidoc[]
 
+include::./running-on-docker.asciidoc[]
+
 //
 //include::./upgrading.asciidoc[]
 
@@ -60,5 +63,5 @@ include::./troubleshooting.asciidoc[]
 
 include::./faq.asciidoc[]
 
-// 
+//
 //include::./heartbeat-devguide.asciidoc[]

heartbeat/docs/running-on-docker.asciidoc

@@ -0,0 +1 @@
+include::../../libbeat/docs/shared-docker.asciidoc[]

libbeat/docs/dashboards.asciidoc

@@ -16,7 +16,7 @@
 
 {beatname_uc} comes packaged with the `scripts/import_dashboards` script that you can use to import the example dashboards,
 visualizations, and searches for {beatname_uc}. The script also creates an index pattern,
-+{beatname_lc}-*+, for {beatname_uc}. 
++{beatname_lc}-*+, for {beatname_uc}.
 
 The steps in this section show how to import {beatname_uc} dashboards. You may want to import dashboards for more than
 one Beat or specify import options that aren't described here. See {beatsdevguide}/import-dashboards.html[Importing Existing Beat Dashboards]
@@ -28,21 +28,28 @@ ifdef::allplatforms[]
 
 *deb, rpm, and mac:*
 
-From the directory where you installed {beatname_uc}, run the `import_dashboards` script. 
+From the directory where you installed {beatname_uc}, run the `import_dashboards` script.
 
 ["source","sh",subs="attributes,callouts"]
 ----------------------------------------------------------------------
 ./scripts/import_dashboards
 ----------------------------------------------------------------------
 
-On deb and rpm, the `scripts` folder is located under the home path, which is +/usr/share/{beatname_lc}/+ unless you change it.
+*docker:*
+
+["source","sh",subs="attributes"]
+----------------------------------------------------------------------
+docker run {dockerimage} ./scripts/import_dashboards
+----------------------------------------------------------------------
+
+On deb, rpm, and docker, the `scripts` folder is located under the home path, which is +/usr/share/{beatname_lc}/+ unless you change it.
 
 By default, the script assumes that you are running Elasticsearch on `127.0.0.1:9200`. Use the `-es` option
-to specify a different location. For example: 
+to specify a different location. For example:
 
 ["source","sh",subs="attributes,callouts"]
 ----------------------------------------------------------------------
-./scripts/import_dashboards -es http://192.168.33.60:9200 
+./scripts/import_dashboards -es http://192.168.33.60:9200
 ----------------------------------------------------------------------
 
 Use the `-user` option to specify the username and password to use for Elasticsearch authentication. There are a few ways to pass
@@ -51,7 +58,7 @@ in the username and password. For example:
 ["source","sh",subs="attributes,callouts"]
 -----------------------------------------------------------------------
 ./scripts/import_dashboards -es https://xyz.found.io -user user -pass password <1>
-./scripts/import_dashboards -es https://xyz.found.io -user admin -pass $(cat ~/pass-file) <2> 
+./scripts/import_dashboards -es https://xyz.found.io -user admin -pass $(cat ~/pass-file) <2>
 -----------------------------------------------------------------------
 
 <1> Specify the username and password as options.
@@ -63,7 +70,7 @@ endif::allplatforms[]
 
 Open a PowerShell prompt as an Administrator (right-click the PowerShell icon
 and select *Run As Administrator*). If you are running Windows XP, you may need
-to download and install PowerShell. 
+to download and install PowerShell.
 
 From the PowerShell prompt, change to the directory where you installed {beatname_uc}, and run the
 `import_dashboards.exe` script:
@@ -103,7 +110,7 @@ pattern is selected to see {beatname_uc} data.
 image:./images/kibana-created-indexes.png[Discover tab with index selected]
 
 To open the loaded dashboards, go to the *Dashboard* page and select the
-dashboard that you want to open. 
+dashboard that you want to open.
 
 image:./images/kibana-navigation-vis.png[Navigation widget in Kibana]
 

libbeat/docs/shared-configuring.asciidoc

@@ -0,0 +1,10 @@
+To configure {beatname_uc}, you edit the configuration file. For rpm and deb,
+you'll find the configuration file at +/etc/{beatname_lc}/{beatname_lc}.yml+. Under
+Docker, it's located at +/usr/share/{beatname_lc}/{beatname_lc}.yml+. For mac and win,
+look in the archive that you just extracted. There’s also a full example
+configuration file called +{beatname_lc}.full.yml+ that shows all non-deprecated
+options.
+
+See the
+{libbeat}/config-file-format.html[Config File Format] section of the
+_Beats Platform Reference_ for more about the structure of the config file.

libbeat/docs/shared-directory-layout.asciidoc

@@ -29,7 +29,7 @@ file.
 
 ==== Default paths
 
-{beatname_uc} uses the following default paths unless you explicitly change them. 
+{beatname_uc} uses the following default paths unless you explicitly change them.
 
 [float]
 ===== deb and rpm
@@ -48,6 +48,18 @@ the systemd unit file.  Make sure that you start the {beatname_uc} service by us
 the preferred operating system method (init scripts or `systemctl`).
 Otherwise the paths might be set incorrectly.
 
+[float]
+===== docker
+[cols="<h,<,<m",options="header",]
+|=======================================================================
+| Type | Description | Location
+| home | Home of the {beatname_uc} installation. | /usr/share/{beatname_lc}
+| bin  | The location for the binary files. | /usr/share/{beatname_lc}
+| conf | The location for configuration files. | /usr/share/{beatname_lc}
+| data | The location for persistent data files. | /usr/share/{beatname_lc}/data
+| logs | The location for the logs created by {beatname_uc}. | /usr/share//{beatname_lc}/logs
+|=======================================================================
+
 [float]
 ===== zip, tar.gz, and tgz
 [cols="<h,<,<m",options="header",]

libbeat/docs/shared-docker.asciidoc

@@ -0,0 +1,61 @@
+[[running-on-docker]]
+== Running {beatname_uc} on Docker
+
+Docker images for {beatname_uc} are available from the Elastic Docker
+registry. You can retrieve an image with a `docker pull` command.
+
+ifeval::["{release-state}"=="unreleased"]
+
+However, version {stack-version} of {beatname_uc} has not yet been
+released, so no Docker image is currently available for this version.
+
+endif::[]
+
+ifeval::["{release-state}"!="unreleased"]
+
+["source", "sh", subs="attributes"]
+------------------------------------------------
+docker pull {dockerimage}
+------------------------------------------------
+
+endif::[]
+
+The base image is https://hub.docker.com/_/centos/[centos:7] and the source
+code can be found on
+https://github.com/elastic/beats-docker/tree/{doc-branch}[GitHub].
+
+[float]
+=== Configuring {beatname_uc} on Docker
+
+The Docker image provides several methods for configuring {beatname_uc}. The
+conventional approach is to provide a configuration file via a bind-mounted
+volume, but it's also possible to create a custom image with your
+configuration included.
+
+[float]
+==== Bind-Mounted Configuration
+
+One way to configure {beatname_uc} on Docker is to provide +{beatname_lc}.yml+ via bind-mounting.
+With +docker run+, the bind-mount can be specified like this:
+
+["source", "sh", subs="attributes"]
+--------------------------------------------
+docker run \
+  -v ~/{beatname_lc}.yml:/usr/share/{beatname_lc}/{beatname_lc}.yml \
+  {dockerimage}
+--------------------------------------------
+
+[float]
+==== Custom Image Configuration
+
+It's possible to embed your {beatname_uc} configuration in a custom image.
+Here is an example Dockerfile to achieve this:
+
+["source", "dockerfile", subs="attributes"]
+--------------------------------------------
+FROM {dockerimage}
+COPY {beatname_lc}.yml /usr/share/{beatname_lc}/{beatname_lc}.yml
+USER root
+RUN chown {beatname_lc} /usr/share/{beatname_lc}/{beatname_lc}.yml
+USER {beatname_lc}
+--------------------------------------------

libbeat/docs/shared-download-and-install.asciidoc

@@ -0,0 +1,13 @@
+To download and install {beatname_uc}, use the commands that work with your system
+(<<deb, deb>> for Debian/Ubuntu, <<rpm, rpm>> for Redhat/Centos/Fedora, <<mac,
+mac>> for OS X, <<docker, docker>> for any Docker platform, and <<win, win>> for
+Windows).
+
+[NOTE]
+==================================================
+If you use Apt or Yum, you can <<setup-repositories,install {beatname_uc} from our
+repositories>> to update to the newest version more easily.
+
+See our https://www.elastic.co/downloads/beats/{beatname_lc}[download page] for
+other installation options, such as 32-bit images.
+==================================================

libbeat/docs/shared-template-load.asciidoc

@@ -78,6 +78,13 @@ cd {beatname_lc}-{version}-darwin-x86_64
 curl -H 'Content-Type: application/json' -XPUT 'http://localhost:9200/_template/{beatname_lc}' -d@{beatname_lc}.template.json
 ----------------------------------------------------------------------
 
+*docker:*
+
+["source", "sh", subs="attributes"]
+----------------------------------------------------------------------
+docker run --rm {dockerimage} curl -H 'Content-Type: application/json' -XPUT 'http://localhost:9200/_template/{beatname_lc}' -d@{beatname_lc}.template.json
+----------------------------------------------------------------------
+
 *win:*
 
 endif::allplatforms[]