diff --git a/docs/reference/index.asciidoc b/docs/reference/index.asciidoc index 317500b474f5c..7a2e2628102f0 100644 --- a/docs/reference/index.asciidoc +++ b/docs/reference/index.asciidoc @@ -3,6 +3,8 @@ :version: 6.0.0-alpha1 :major-version: 6.x +:docker-image: docker.elastic.co/elasticsearch/elasticsearch:{version} +:x-pack-baseurl: https://www.elastic.co/guide/en/x-pack/5.0 ////////// release-state can be: released | prerelease | unreleased diff --git a/docs/reference/setup/install.asciidoc b/docs/reference/setup/install.asciidoc index 322bd0e0d2424..c4ab12fb3f941 100644 --- a/docs/reference/setup/install.asciidoc +++ b/docs/reference/setup/install.asciidoc @@ -27,6 +27,12 @@ Elasticsearch website or from our RPM repository. + <> +`docker`:: + +An image is available for running Elasticsearch as a Docker container. It ships with https://www.elastic.co/guide/en/x-pack/current/index.html[X-Pack] pre-installed and may be downloaded from the Elastic Docker Registry. ++ +<> + [float] [[config-mgmt-tools]] === Configuration Management Tools @@ -47,4 +53,4 @@ include::install/rpm.asciidoc[] include::install/windows.asciidoc[] - +include::install/docker.asciidoc[] diff --git a/docs/reference/setup/install/docker.asciidoc b/docs/reference/setup/install/docker.asciidoc new file mode 100644 index 0000000000000..ac98af2ccaacb --- /dev/null +++ b/docs/reference/setup/install/docker.asciidoc @@ -0,0 +1,300 @@ +[[docker]] +=== Install Elasticsearch with Docker + +Elasticsearch is also available as a Docker image. +The image is built with {x-pack-baseurl}/index.html[X-Pack]. + +==== Security note + +NOTE: {x-pack-baseurl}/index.html[X-Pack] is preinstalled in this image. +Please take a few minutes to familiarize yourself with {x-pack-baseurl}/security-getting-started.html[X-Pack Security] and how to change default passwords. The default password for the `elastic` user is `changeme`. + +NOTE: X-Pack includes a trial license for 30 days. After that, you can obtain one of the https://www.elastic.co/subscriptions[available subscriptions] or {x-pack-baseurl}/security-settings.html[disable Security]. The Basic license is free and includes the https://www.elastic.co/products/x-pack/monitoring[Monitoring] extension. + +Obtaining Elasticsearch for Docker is as simple as issuing a +docker pull+ command against the Elastic Docker registry. + +ifeval::["{release-state}"=="unreleased"] + +WARNING: Version {version} of Elasticsearch has not yet been released, so no Docker image is currently available for this version. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +The Docker image can be retrieved with the following command: + +["source","sh",subs="attributes"] +-------------------------------------------- +docker pull {docker-image} +-------------------------------------------- + +endif::[] + +[[docker-cli-run]] +==== Running Elasticsearch from the command line + +[[docker-cli-run-dev-mode]] +===== Development mode + +ifeval::["{release-state}"=="unreleased"] + +WARNING: Version {version} of the Elasticsearch Docker image has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +Elasticsearch can be quickly started for development or testing use with the following command: + +["source","sh",subs="attributes"] +-------------------------------------------- +docker run -p 9200:9200 -e "http.host=0.0.0.0" -e "transport.host=127.0.0.1" {docker-image} +-------------------------------------------- + +endif::[] + +[[docker-cli-run-prod-mode]] +===== Production mode + +[[docker-prod-prerequisites]] +[IMPORTANT] +========================= + +The `vm_max_map_count` kernel setting needs to be set to at least `262144` for production use. +Depending on your platform: + +* Linux ++ +The `vm_map_max_count` setting should be set permanently in /etc/sysctl.conf: ++ +[source,sh] +-------------------------------------------- +$ grep vm.max_map_count /etc/sysctl.conf +vm.max_map_count=262144 +---------------------------------- ++ +To apply the setting on a live system type: `sysctl -w vm.max_map_count=262144` ++ +* OSX with https://docs.docker.com/engine/installation/mac/#/docker-for-mac[Docker for Mac] ++ +The `vm_max_map_count` setting must be set within the xhyve virtual machine: ++ +["source","sh"] +-------------------------------------------- +$ screen ~/Library/Containers/com.docker.docker/Data/com.docker.driver.amd64-linux/tty +-------------------------------------------- ++ +Log in with 'root' and no password. +Then configure the `sysctl` setting as you would for Linux: ++ +["source","sh"] +-------------------------------------------- +sysctl -w vm.max_map_count=262144 +-------------------------------------------- ++ +* OSX with https://docs.docker.com/engine/installation/mac/#docker-toolbox[Docker Toolbox] ++ +The `vm_max_map_count` setting must be set via docker-machine: ++ +["source","sh"] +-------------------------------------------- +docker-machine ssh +sudo sysctl -w vm.max_map_count=262144 +-------------------------------------------- +========================= + +The following example brings up a cluster comprising two Elasticsearch nodes. +To bring up the cluster, use the <> and just type: + +ifeval::["{release-state}"=="unreleased"] + +WARNING: Version {version} of the Elasticsearch Docker image has not yet been released, so a `docker-compose.yml` is not available for this version. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +["source","sh"] +-------------------------------------------- +docker-compose up +-------------------------------------------- + +endif::[] + +[NOTE] +`docker-compose` is not pre-installed with Docker on Linux. +Instructions for installing it can be found on the https://docs.docker.com/compose/install/#install-using-pip[docker-compose webpage]. + +The node `elasticsearch1` listens on `localhost:9200` while `elasticsearch2` talks to `elasticsearch1` over a Docker network. + +This example also uses https://docs.docker.com/engine/tutorials/dockervolumes[Docker named volumes], called `esdata1` and `esdata2` which will be created if not already present. + +[[docker-prod-cluster-composefile]] +`docker-compose.yml`: +ifeval::["{release-state}"=="unreleased"] + +WARNING: Version {version} of the Elasticsearch Docker image has not yet been released, so a `docker-compose.yml` is not available for this version. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] +["source","yaml",subs="attributes"] +-------------------------------------------- +version: '2' +services: + elasticsearch1: + image: docker.elastic.co/elasticsearch/elasticsearch:{version} + container_name: elasticsearch1 + environment: + - cluster.name=docker-cluster + - bootstrap.memory_lock=true + - "ES_JAVA_OPTS=-Xms512m -Xmx512m" + ulimits: + memlock: + soft: -1 + hard: -1 + nofile: + soft: 65536 + hard: 65536 + mem_limit: 1g + cap_add: + - IPC_LOCK + volumes: + - esdata1:/usr/share/elasticsearch/data + ports: + - 9200:9200 + networks: + - esnet + elasticsearch2: + image: docker.elastic.co/elasticsearch/elasticsearch:{version} + environment: + - cluster.name=docker-cluster + - bootstrap.memory_lock=true + - "ES_JAVA_OPTS=-Xms512m -Xmx512m" + - "discovery.zen.ping.unicast.hosts=elasticsearch1" + ulimits: + memlock: + soft: -1 + hard: -1 + nofile: + soft: 65536 + hard: 65536 + mem_limit: 1g + cap_add: + - IPC_LOCK + volumes: + - esdata2:/usr/share/elasticsearch/data + networks: + - esnet + +volumes: + esdata1: + driver: local + esdata2: + driver: local + +networks: + esnet: + driver: bridge +-------------------------------------------- +endif::[] + +To stop the cluster, type `docker-compose down`. Data volumes will persist, so it's possible to start the cluster again with the same data using `docker-compose up`. +To destroy the cluster **and the data volumes** just type `docker-compose down -v`. + +===== Inspect status of cluster: + +["source","sh"] +-------------------------------------------- +curl -u elastic http://127.0.0.1:9200/_cat/health +Enter host password for user 'elastic': +1472225929 15:38:49 docker-cluster green 2 2 4 2 0 0 0 0 - 100.0% +-------------------------------------------- + +Log messages go to the console and are handled by the configured Docker logging driver. By default you can access logs with `docker logs`. + +[[docker-configuration-methods]] +==== Configuring Elasticsearch with Docker + +Elasticsearch loads its configuration from files under `/usr/share/elasticsearch/config/`. These configuration files are documented in <> and <>. + +The image offers several methods for configuring Elasticsearch settings with the conventional approach being to provide customized files, i.e. `elasticsearch.yml`, but it's also possible to use environment variables to set options: + +===== A. Present the parameters via Docker environment variables +For example, to define the cluster name with `docker run` you can pass `-e "cluster.name=mynewclustername"`. Double quotes are required. + +NOTE: There is a difference between defining <<_setting_default_settings,default settings>> and normal settings. The former are prefixed with `default.` and cannot override normal settings, if defined. + +===== B. Bind-mounted configuration +Create your custom config file and mount this over the image's corresponding file. +For example, bind-mounting a `custom_elasticsearch.yml` with `docker run` can be accomplished with the parameter: + +["source","sh"] +-------------------------------------------- +-v full_path_to/custom_elasticsearch.yml:/usr/share/elasticsearch/config/elasticsearch.yml +-------------------------------------------- + +IMPORTANT: `custom_elasticsearch.yml` should be readable by uid:gid `1000:1000` + +===== C. Customized image +In some environments, it may make more sense to prepare a custom image containing your configuration. A `Dockerfile` to achieve this may be as simple as: + +["source","sh",subs="attributes"] +-------------------------------------------- +FROM docker.elastic.co/elasticsearch/elasticsearch:{version} +ADD elasticsearch.yml /usr/share/elasticsearch/config/ +USER root +chown elasticsearch:elasticsearch config/elasticsearch.yml +USER elasticsearch +-------------------------------------------- + +You could then build and try the image with something like: + +["source","sh"] +-------------------------------------------- +docker build --tag=elasticsearch-custom . +docker run -ti -v /usr/share/elasticsearch/data elasticsearch-custom +-------------------------------------------- + +===== D. Override the image's default https://docs.docker.com/engine/reference/run/#cmd-default-command-or-options[CMD] + +Options can be passed as command-line options to the Elasticsearch process by +overriding the default command for the image. For example: + +["source","sh"] +-------------------------------------------- +docker run bin/elasticsearch -Ecluster.name=mynewclustername +-------------------------------------------- + +==== Notes for production use and defaults + +We have collected a number of best practices for production use. + +NOTE: Any Docker parameters mentioned below assume the use of `docker run`. + +. It is important to correctly set capabilities and ulimits via the Docker CLI. As seen earlier in the example <>, the following options are required: ++ + --cap-add=IPC_LOCK --ulimit memlock=-1:-1 --ulimit nofile=65536:65536 ++ +. Ensure `bootstrap.memory_lock` is set to `true` as explained in "<>". ++ +This can be achieved through any of the <>, e.g. by setting the appropriate environments variable with `-e "bootstrap.memory_lock=true"`. ++ +. The image https://docs.docker.com/engine/reference/builder/#/expose[exposes] TCP ports 9200 and 9300. For clusters it is recommended to randomize the published ports with `--publish-all`, unless you are pinning one container per host. ++ +. Use the `ES_JAVA_OPTS` environment variable to set heap size, e.g. to use 16GB use `-e ES_JAVA_OPTS="-Xms16g -Xmx16g"` with `docker run`. It is also recommended to set a https://docs.docker.com/engine/reference/run/#user-memory-constraints[memory limit] for the container. ++ +. Pin your deployments to a specific version of the Elasticsearch Docker image, e.g. +docker.elastic.co/elasticsearch/elasticsearch:{version}+. ++ +. Always use a volume bound on `/usr/share/elasticsearch/data`, as shown in the <>, for the following reasons: ++ +.. The data of your elasticsearch node won't be lost if the container is killed +.. Elasticsearch is I/O sensitive and the Docker storage driver is not ideal for fast I/O +.. It allows the use of advanced https://docs.docker.com/engine/extend/plugins/#volume-plugins[Docker volume plugins] ++ +. If you are using the devicemapper storage driver (default on at least RedHat (rpm) based distributions) make sure you are not using the default `loop-lvm` mode. Configure docker-engine to use https://docs.docker.com/engine/userguide/storagedriver/device-mapper-driver/#configure-docker-with-devicemapper[direct-lvm] instead. ++ +. Consider centralizing your logs by using a different https://docs.docker.com/engine/admin/logging/overview/[logging driver]. Also note that the default json-file logging driver is not ideally suited for production use. + + +include::next-steps.asciidoc[]