[[docker]]
== Running Kibana on Docker
Docker images for Kibana are available from the Elastic Docker registry. The
base image is https://hub.docker.com/_/centos/[centos:7].

A list of all published Docker images and tags is available at
https://www.docker.elastic.co[www.docker.elastic.co]. The source code is in
https://github.com/elastic/kibana-docker/tree/{branch}[GitHub].

These images are free to use under the Elastic license. They contain open source 
and free commercial features and access to paid commercial features.  
{xpack-ref}/license-management.html[Start a 30-day trial] to try out all of the 
paid commercial features. See the 
https://www.elastic.co/subscriptions[Subscriptions] page for information about 
Elastic license levels.

[float]
[[pull-image]]
=== 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"]

["source","txt",subs="attributes"]
--------------------------------------------
docker pull {docker-repo}:{version}
--------------------------------------------

Alternatively, you can download other Docker images that contain only features 
available under the Apache 2.0 license. To download the images, go to 
https://www.docker.elastic.co[www.docker.elastic.co].

endif::[]

[float]
[[configuring-kibana-docker]]
=== Configuring Kibana on Docker

The Docker images provide several methods for configuring Kibana. The
conventional approach is to provide a `kibana.yml` file as described in
{kibana-ref}/settings.html[Configuring Kibana], but it's also possible to use
environment variables to define settings.

[float]
[[bind-mount-config]]
==== 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"]
--------------------------------------------
version: '2'
services:
  kibana:
    image: {docker-image}
    volumes:
      - ./kibana.yml:/usr/share/kibana/config/kibana.yml
--------------------------------------------

[float]
[[environment-variable-config]]
==== Environment variable configuration

Under Docker, Kibana can be configured via environment variables. When
the container starts, a helper process checks the environment for variables that
can be mapped to Kibana command-line arguments.

For compatibility with container orchestration systems, these
environment variables are written in all capitals, with underscores as
word separators. The helper translates these names to valid
Kibana setting names.

Some example translations are shown here:

.Example Docker Environment Variables
[horizontal]
**Environment Variable**:: **Kibana Setting**
`SERVER_NAME`:: `server.name`
`KIBANA_DEFAULTAPPID`:: `kibana.defaultAppId`
`XPACK_MONITORING_ENABLED`:: `xpack.monitoring.enabled`

In general, any setting listed in <<settings>> or <<settings-xpack-kb>> can be 
configured with this technique.

These variables can be set with +docker-compose+ like this:

["source","yaml",subs="attributes"]
----------------------------------------------------------
version: '2'
services:
  kibana:
    image: {docker-image}
    environment:
      SERVER_NAME: kibana.example.org
      ELASTICSEARCH_HOSTS: http://elasticsearch.example.org
----------------------------------------------------------

Since environment variables are translated to CLI arguments, they take
precedence over settings configured in `kibana.yml`.

[float]
[[docker-defaults]]
==== Docker defaults
The following settings have different default values when using the Docker
images:

[horizontal]
`server.name`:: `kibana`
`server.host`:: `"0"`
`elasticsearch.hosts`:: `http://elasticsearch:9200`
`xpack.monitoring.ui.container.elasticsearch.enabled`:: `true`

NOTE: The setting `xpack.monitoring.ui.container.elasticsearch.enabled` is not
defined in the `-oss` image.

These settings are defined in the default `kibana.yml`. They can be overridden
with a <<bind-mount-config,custom `kibana.yml`>> or via
<<environment-variable-config,environment variables>>.

IMPORTANT: If replacing `kibana.yml` with a custom version, be sure to copy the
above defaults to the custom file if you want to retain them. If not, they will
be "masked" by the new file.