[[docker]]
=== Install {kib} with Docker
++++
<titleabbrev>Install with Docker</titleabbrev>
++++

:kib-docker-repo:     docker.elastic.co/kibana/kibana
:kib-docker-image:    {kib-docker-repo}:{version}
:es-docker-repo:      docker.elastic.co/elasticsearch/elasticsearch
:es-docker-image:     {es-docker-repo}:{version}

Docker images for {kib} are available from the Elastic Docker registry. The
base image is https://hub.docker.com/_/ubuntu[ubuntu:20.04].

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/dockerfiles/tree/{branch}/kibana[GitHub].

These images contain both free and subscription features.
<<managing-licenses,Start a 30-day trial>> to try out all of the features.

[discrete]
[[run-kibana-on-docker-for-dev]]
=== Run {kib} in Docker for development

Use Docker commands to run {kib} on a single-node {es} cluster for development or
testing.

TIP: This setup doesn't run multiple {es} nodes by default. To create a
multi-node cluster with {kib}, use Docker Compose instead. Refer to
{ref}/docker.html#docker-compose-file[Start a multi-node cluster with Docker
Compose] in the {es} documentation.

. Install Docker. Visit https://docs.docker.com/get-docker/[Get Docker] to
install Docker for your environment.
+
IMPORTANT: If using Docker Desktop, make sure to allocate at least 4GB of
memory. You can adjust memory usage in Docker Desktop by going to **Settings >
Resources**.

. Create a new Docker network for {es} and {kib}.
+
[source,sh,subs="attributes"]
----
docker network create elastic
----

. Pull the {es} Docker image.
+
--
ifeval::["{release-state}"=="unreleased"]
WARNING: Version {version} has not yet been released.
No Docker image is currently available for {es} {version}.
endif::[]

[source,sh,subs="attributes"]
----
docker pull {es-docker-image}
----
--

. Optional: Install
https://docs.sigstore.dev/system_config/installation/[Cosign] for your
environment. Then use Cosign to verify the {es} image's signature.
+
[source,sh,subs="attributes"]
----
wget https://artifacts.elastic.co/cosign.pub
cosign verify --key cosign.pub {es-docker-image}
----
+
The `cosign` command prints the check results and the signature payload in JSON format:
+
[source,sh,subs="attributes"]
--------------------------------------------
Verification for {es-docker-image} --
The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - Existence of the claims in the transparency log was verified offline
  - The signatures were verified against the specified public key
--------------------------------------------

. Start an {es} container.
+
[source,sh,subs="attributes"]
----
docker run --name es01 --net elastic -p 9200:9200 -it -m 1GB {es-docker-image}
----
+
TIP: Use the `-m` flag to set a memory limit for the container. This removes the
need to {ref}/docker.html#docker-set-heap-size[manually set the JVM size].
+
The command prints the `elastic` user password and an enrollment token for {kib}.

. Copy the generated `elastic` password and enrollment token. These credentials
are only shown when you start {es} for the first time. You can regenerate the
credentials using the following commands.
+
[source,sh,subs="attributes"]
----
docker exec -it es01 /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
docker exec -it es01 /usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s kibana
----

. Pull the {kib} Docker image.
+
--
ifeval::["{release-state}"=="unreleased"]
WARNING: Version {version} has not yet been released.
No Docker image is currently available for {kib} {version}.
endif::[]

[source,sh,subs="attributes"]
----
docker pull {kib-docker-image}
----
--

. Optional: Verify the {kib} image's signature.
+
[source,sh,subs="attributes"]
----
wget https://artifacts.elastic.co/cosign.pub
cosign verify --key cosign.pub {kib-docker-image}
----

. Start a {kib} container.
+
[source,sh,subs="attributes"]
----
docker run --name kib01 --net elastic -p 5601:5601 {kib-docker-image}
----

. When {kib} starts, it outputs a unique generated link to the terminal. To
access {kib}, open this link in a web browser.

. In your browser, enter the enrollment token that was generated when you started {es}.
+
To regenerate the token, run:
+
[source,sh]
----
docker exec -it es01 /usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s kibana
----

. Log in to {kib} as the `elastic` user with the password that was generated
when you started {es}.
+
To regenerate the password, run:
+
[source,sh]
----
docker exec -it es01 /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
----

[discrete]
==== Remove Docker containers

To remove the containers and their network, run:

[source,sh,subs="attributes"]
----
# Remove the Elastic network
docker network rm elastic

# Remove the {es} container
docker rm es01

# Remove the {kib} container
docker rm kib01
----

[discrete]
[[configuring-kibana-docker]]
=== Configure {kib} on Docker

The Docker images provide several methods for configuring {kib}. 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.

[discrete]
[[bind-mount-config]]
==== Bind-mounted configuration

One way to configure {kib} 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: {kib-docker-image}
    volumes:
      - ./kibana.yml:/usr/share/kibana/config/kibana.yml
--------------------------------------------

==== Persist the {kib} keystore

By default, {kib} auto-generates a keystore file for secure settings at startup. To persist your {kibana-ref}/secure-settings.html[secure settings], use the `kibana-keystore` utility to bind-mount the parent directory of the keystore to the container. For example:

["source","sh",subs="attributes"]
----
docker run -it --rm -v full_path_to/config:/usr/share/kibana/config -v full_path_to/data:/usr/share/kibana/data {kib-docker-image} bin/kibana-keystore create
docker run -it --rm -v full_path_to/config:/usr/share/kibana/config -v full_path_to/data:/usr/share/kibana/data {kib-docker-image} bin/kibana-keystore add test_keystore_setting
----

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

Under Docker, {kib} 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
{kib} setting names.

WARNING: All information that you include in environment variables is visible through the `ps` command, including sensitive information.

Some example translations are shown here:

.Example Docker Environment Variables
[horizontal]
**Environment Variable**:: **Kibana Setting**
`SERVER_NAME`:: `server.name`
`SERVER_BASEPATH`:: `server.basePath`
`ELASTICSEARCH_HOSTS`:: `elasticsearch.hosts`

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

Supplying array options can be tricky. The following example shows the syntax for providing an array to `ELASTICSEARCH_HOSTS`.

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

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

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

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

[horizontal]
`server.host`:: `"0.0.0.0"`
`server.shutdownTimeout`:: `"5s"`
`elasticsearch.hosts`:: `http://elasticsearch:9200`
`monitoring.ui.container.elasticsearch.enabled`:: `true`

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
defaults to the custom file if you want to retain them. If not, they will
be "masked" by the new file.
