Add docs for Docker images (elastic#4312)

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:*
 
@@ -139,15 +147,7 @@ started, you can skip the content in this section, including the remaining
 getting started steps, and go directly to the <<filebeat-modules-quickstart>>
 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

@@ -15,6 +15,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[]
 
@@ -28,6 +29,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

@@ -15,6 +15,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[]
 
@@ -26,6 +27,8 @@ include::../../libbeat/docs/shared-directory-layout.asciidoc[]
 
 include::../../libbeat/docs/repositories.asciidoc[]
 
+include::./running-on-docker.asciidoc[]
+
 //
 //include::./upgrading.asciidoc[]
 
@@ -58,5 +61,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 {libbeat}/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,6 +110,6 @@ 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[]