Docs: Using the Docker image (#9060)

docs/index.asciidoc

@@ -3,6 +3,7 @@
 
 :version:        5.1.0
 :major-version:  5.x
+:docker-image:   docker.elastic.co/kibana/kibana:{version}
 
 //////////
 release-state can be: released | prerelease | unreleased

docs/setup.asciidoc

@@ -50,6 +50,8 @@ include::setup/install.asciidoc[]
 
 include::setup/settings.asciidoc[]
 
+include::setup/docker.asciidoc[]
+
 include::setup/access.asciidoc[]
 
 include::setup/connect-to-elasticsearch.asciidoc[]

docs/setup/docker.asciidoc

@@ -0,0 +1,116 @@
+[[docker]]
+== Running Kibana on Docker
+Docker images for Kibana are available from the Elastic Docker registry.
+The images are shipped with https://www.elastic.co/products/x-pack[X-Pack]
+installed.
+
+NOTE: https://www.elastic.co/guide/en/x-pack/current/index.html[X-Pack] is
+pre-installed in this image. With X-Pack installed, Kibana expects to
+connect to an Elasticsearch cluster that is also runnning X-Pack. The
+{es-ref}/docker.html[Elasticsearch Docker image] is built to match.
+
+=== Pulling the image
+Obtaining Kibana for Docker is as simple as issuing a +docker pull+ command
+against the Elastic Docker registry.
+
+ifeval::["{release-state}"=="unreleased"]
+
+However, version {version} of Kibana has not yet been released, so no Docker
+image is currently available for this version.
+
+endif::[]
+
+ifeval::["{release-state}"!="unreleased"]
+
+The Docker image for Kibana v{version} can be retrieved with the following
+command:
+
+["source","sh",subs="attributes"]
+--------------------------------------------
+docker pull {docker-image}
+--------------------------------------------
+
+endif::[]
+
+=== Configuring Kibana on Docker
+
+The Docker image provides several methods for configuring Kibana. The conventional
+approach is to provide a `kibana.yml` file as described in <<settings>>, but it's
+also possible to use environment variables to define settings.
+
+==== Bind-mounted configuration
+
+One way to configure Kibana on Docker is to provide `kibana.yml` via bind-mounting.
+With +docker-compose+, the bind-mount can be specified like this:
+
+["source","yaml",subs="attributes"]
+--------------------------------------------
+services:
+  kibana:
+    image: {docker-image}
+    volumes:
+      - ./kibana.yml:/usr/share/kibana/config/kibana.yml
+--------------------------------------------
+
+==== Environment variable configuration
+
+Under Docker, Kibana can be configured via environment variables. The following
+mappings are available:
+
+.Docker Environment Variables
+[horizontal]
+**Environment Variable**:: **Kibana Setting**
+`ELASTICSEARCH_CUSTOMHEADERS`:: `elasticsearch.customHeaders`
+`ELASTICSEARCH_PASSWORD`:: `elasticsearch.password`
+`ELASTICSEARCH_PINGTIMEOUT`:: `elasticsearch.pingTimeout`
+`ELASTICSEARCH_PRESERVEHOST`:: `elasticsearch.preserveHost`
+`ELASTICSEARCH_REQUESTHEADERSWHITELIST`:: `elasticsearch.requestHeadersWhitelist`
+`ELASTICSEARCH_REQUESTTIMEOUT`:: `elasticsearch.requestTimeout`
+`ELASTICSEARCH_SHARDTIMEOUT`:: `elasticsearch.shardTimeout`
+`ELASTICSEARCH_SSL_CA`:: `elasticsearch.ssl.ca`
+`ELASTICSEARCH_SSL_CERT`:: `elasticsearch.ssl.cert`
+`ELASTICSEARCH_SSL_KEY`:: `elasticsearch.ssl.key`
+`ELASTICSEARCH_SSL_VERIFY`:: `elasticsearch.ssl.verify`
+`ELASTICSEARCH_STARTUPTIMEOUT`:: `elasticsearch.startupTimeout`
+`ELASTICSEARCH_URL`:: `elasticsearch.url`
+`ELASTICSEARCH_USERNAME`:: `elasticsearch.username`
+`KIBANA_DEFAULTAPPID`:: `kibana.defaultAppId`
+`KIBANA_INDEX`:: `kibana.index`
+`LOGGING_DEST`:: `logging.dest`
+`LOGGING_QUIET`:: `logging.quiet`
+`LOGGING_SILENT`:: `logging.silent`
+`LOGGING_VERBOSE`:: `logging.verbose`
+`OPS_INTERVAL`:: `ops.interval`
+`PID_FILE`:: `pid.file`
+`SERVER_BASEPATH`:: `server.basePath`
+`SERVER_HOST`:: `server.host`
+`SERVER_MAXPAYLOADBYTES`:: `server.maxPayloadBytes`
+`SERVER_NAME`:: `server.name`
+`SERVER_PORT`:: `server.port`
+`SERVER_SSL_CERT`:: `server.ssl.cert`
+`SERVER_SSL_KEY`:: `server.ssl.key`
+
+These variables can be set with +docker-compose+ like this:
+
+["source","yaml",subs="attributes"]
+----------------------------------------------------------
+services:
+  kibana:
+    image: {docker-image}
+    environment:
+      SERVER_NAME: kibana.example.org
+      ELASTICSEARCH_URL: http://elasticsearch.example.org
+----------------------------------------------------------
+
+Environment variables take precedence over settings configured in `kibana.yml`.
+
+==== Docker defaults
+The following settings have different default values when using the Docker image:
+
+[horizontal]
+`server.host`:: `"0"`
+`elasticsearch.url`:: `http://elasticsearch:9200`
+`elasticsearch.username`:: `elastic`
+`elasticsearch.password`:: `changeme`
+
+

docs/setup/install.asciidoc

@@ -29,6 +29,15 @@ Elastic website or from our RPM repository.
 +
 <<rpm>>
 
+`docker`::
+
+An image is available for running Kibana as a Docker container. It ships
+with https://www.elastic.co/products/x-pack[X-Pack] pre-installed and is
+available from the Elastic
+Docker registry.
++
+<<docker>>
+
 IMPORTANT: If your Elasticsearch installation is protected by {xpack-ref}xpack-security.html[X-Pack Security]
 see {xpack-ref}kibana.html[Using Kibana with X-Pack Security] for additional setup
 instructions.