[[docker]] === Install {kib} with Docker ++++ Install with Docker ++++ :docker-repo: docker.elastic.co/kibana/kibana :docker-image: {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. <> to try out all of the features. [discrete] [[run-kibana-on-docker-for-dev]] === Run {kib} on Docker for development . Start an {es} container for development or testing: + -- ifeval::["{release-state}"=="unreleased"] NOTE: No Docker images are currently available for {kib} {version}. endif::[] ifeval::["{release-state}"!="unreleased"] .. Create a new Docker network for {es} and {kib}: + [source,sh,subs="attributes"] ---- docker network create elastic ---- .. Pull the {es} Docker image: + [source,sh,subs="attributes"] ---- docker pull {es-docker-image} ---- .. Optional: Verify the {es} Docker image signature:: + [source,sh,subs="attributes"] ---- wget https://artifacts.elastic.co/cosign.pub cosign verify --key cosign.pub {docker-repo}:{version} ---- + For details about this step, refer to {ref}/docker.html#docker-verify-signature[Verify the {es} Docker image signature] in the {es} documentation. .. Start {es} in Docker: + [source,sh,subs="attributes"] ---- docker run --name es-node01 --net elastic -p 9200:9200 -p 9300:9300 -t {es-docker-image} ---- endif::[] -- + When you start {es} for the first time, the following security configuration occurs automatically: + * {ref}/configuring-stack-security.html#stack-security-certificates[Certificates and keys] are generated for the transport and HTTP layers. * The Transport Layer Security (TLS) configuration settings are written to `elasticsearch.yml`. * A password is generated for the `elastic` user. * An enrollment token is generated for {kib}. + NOTE: You might need to scroll back a bit in the terminal to view the password and enrollment token. . Copy the generated password and enrollment token and save them in a secure location. These values are shown only when you start {es} for the first time. You'll use these to enroll {kib} with your {es} cluster and log in. . In a new terminal session, start {kib} and connect it to your {es} container: + -- ifeval::["{release-state}"=="unreleased"] NOTE: No Docker images are currently available for {kib} {version}. endif::[] ifeval::["{release-state}"!="unreleased"] [source,sh,subs="attributes"] ---- docker pull {docker-image} docker run --name kib-01 --net elastic -p 5601:5601 {docker-image} ---- .. Pull the {kib} Docker image: + [source,sh,subs="attributes"] ---- docker pull {docker-image} ---- .. Optional: Verify the {kib} Docker image signature:: + [source,sh,subs="attributes"] ---- wget https://artifacts.elastic.co/cosign.pub cosign verify --key cosign.pub {docker-repo}:{version} ---- + For details about this step, refer to {ref}/docker.html#docker-verify-signature[Verify the {es} Docker image signature] in the {es} documentation. .. Start {kib} in Docker: + [source,sh,subs="attributes"] ---- docker run --name kib-01 --net elastic -p 5601:5601 {docker-image} ---- endif::[] -- + When you start {kib}, a unique link is output to your terminal. . To access {kib}, click the generated link in your terminal. .. In your browser, paste the enrollment token that you copied when starting {es} and click the button to connect your {kib} instance with {es}. .. Log in to {kib} as the `elastic` user with the password that was generated when you started {es}. [[docker-generate]] [discrete] === Generate passwords and enrollment tokens If you need to reset the password for the `elastic` user or other built-in users, run the {ref}/reset-password.html[`elasticsearch-reset-password`] tool. This tool is available in the {es} `bin` directory of the Docker container. For example, to reset the password for the `elastic` user: [source,sh] ---- docker exec -it es-node01 /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic ---- If you need to generate new enrollment tokens for {kib} or {es} nodes, run the {ref}/create-enrollment-token.html[`elasticsearch-create-enrollment-token`] tool. This tool is available in the {es} `bin` directory of the Docker container. For example, to generate a new enrollment token for {kib}: [source,sh] ---- docker exec -it es-node01 /usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s kibana ---- [discrete] === Remove Docker containers To remove the containers and their network, run: [source,sh] ---- docker network rm elastic docker rm es-node01 docker rm kib-01 ---- [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: {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 {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 {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 <> 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: {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 <> or via <>. 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.