From 6ba429a47640a439e11e0e08fc8ae2e77ac294c5 Mon Sep 17 00:00:00 2001
From: lcawley <lcawley@elastic.co>
Date: Thu, 9 Nov 2017 10:27:15 -0800
Subject: [PATCH] [DOCS] Move X-Pack-specific Docker content
---
docs/reference/setup/install.asciidoc | 7 +-
docs/reference/setup/install/docker.asciidoc | 336 -------------------
2 files changed, 6 insertions(+), 337 deletions(-)
delete mode 100644 docs/reference/setup/install/docker.asciidoc
diff --git a/docs/reference/setup/install.asciidoc b/docs/reference/setup/install.asciidoc
index babdccc2d95fe..b77699158326e 100644
--- a/docs/reference/setup/install.asciidoc
+++ b/docs/reference/setup/install.asciidoc
@@ -66,4 +66,9 @@ include::install/rpm.asciidoc[]
include::install/windows.asciidoc[]
-include::install/docker.asciidoc[]
+ifdef::include-xpack[]
+:edit_url!:
+include::{xes-repo-dir}/setup/docker.asciidoc[]
+
+:edit_url:
+endif::include-xpack[]
diff --git a/docs/reference/setup/install/docker.asciidoc b/docs/reference/setup/install/docker.asciidoc
deleted file mode 100644
index 1bcdefc5bc2b5..0000000000000
--- a/docs/reference/setup/install/docker.asciidoc
+++ /dev/null
@@ -1,336 +0,0 @@
-[[docker]]
-=== Install Elasticsearch with Docker
-
-Elasticsearch is also available as Docker images.
-The images use https://hub.docker.com/_/centos/[centos:7] as the base image and
-are available with {xpack-ref}/xpack-introduction.html[X-Pack].
-
-A list of all published Docker images and tags can be found in https://www.docker.elastic.co[www.docker.elastic.co]. The source code can be found
-on https://github.com/elastic/elasticsearch-docker/tree/{branch}[GitHub].
-
-==== Image types
-
-The images are available in three different configurations or "flavors". The
-`basic` flavor, which is the default, ships with X-Pack Basic features
-pre-installed and automatically activated with a free licence. The `platinum`
-flavor features all X-Pack functionally under a 30-day trial licence. The `oss`
-flavor does not include X-Pack, and contains only open-source Elasticsearch.
-
-NOTE: {xpack-ref}/xpack-security.html[X-Pack Security] is enabled in the `platinum`
-image. To access your cluster, it's necessary to set an initial password for the
-`elastic` user. The initial password can be set at start up time via the
-`ELASTIC_PASSWORD` environment variable:
-
-["source","txt",subs="attributes"]
---------------------------------------------
-docker run -e ELASTIC_PASSWORD=MagicWord {docker-repo}-platinum:{version}
---------------------------------------------
-
-NOTE: The `platinum` image includes a trial license for 30 days. After that, you
-can obtain one of the https://www.elastic.co/subscriptions[available
-subscriptions] or revert to a Basic licence. The Basic license is free and
-includes a selection of X-Pack features.
-
-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"]
-
-Docker images can be retrieved with the following commands:
-
-["source","sh",subs="attributes"]
---------------------------------------------
-docker pull {docker-repo}:{version}
-docker pull {docker-repo}-platinum:{version}
-docker pull {docker-repo}-oss:{version}
---------------------------------------------
-
-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 -p 9300:9300 -e "discovery.type=single-node" {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.max_map_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`
-+
-* macOS 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
---------------------------------------------
-+
-* Windows and macOS with https://www.docker.com/products/docker-toolbox[Docker Toolbox]
-+
-The `vm.max_map_count` setting must be set via docker-machine:
-+
-["source","txt"]
---------------------------------------------
-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 <<docker-prod-cluster-composefile,`docker-compose.yml`>> and just type:
-
-ifeval::["{release-state}"=="unreleased"]
-
-WARNING: Version {version} of Elasticsearch 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 `elasticsearch` listens on `localhost:9200` while `elasticsearch2`
-talks to `elasticsearch` 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 Elasticsearch 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.2
-services:
- elasticsearch:
- image: {docker-image}
- container_name: elasticsearch
- environment:
- - cluster.name=docker-cluster
- - bootstrap.memory_lock=true
- - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
- ulimits:
- memlock:
- soft: -1
- hard: -1
- volumes:
- - esdata1:/usr/share/elasticsearch/data
- ports:
- - 9200:9200
- networks:
- - esnet
- elasticsearch2:
- image: {docker-image}
- container_name: elasticsearch2
- environment:
- - cluster.name=docker-cluster
- - bootstrap.memory_lock=true
- - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
- - "discovery.zen.ping.unicast.hosts=elasticsearch"
- ulimits:
- memlock:
- soft: -1
- hard: -1
- volumes:
- - esdata2:/usr/share/elasticsearch/data
- networks:
- - esnet
-
-volumes:
- esdata1:
- driver: local
- esdata2:
- driver: local
-
-networks:
- esnet:
---------------------------------------------
-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","txt"]
---------------------------------------------
-curl http://127.0.0.1:9200/_cat/health
-1472225929 15:38:49 docker-cluster green 2 2 4 2 0 0 0 0 - 100.0%
---------------------------------------------
-// NOTCONSOLE
-
-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 <<settings>> and <<jvm-options>>.
-
-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.
-
-===== 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: The container **runs Elasticsearch as user `elasticsearch` using uid:gid `1000:1000`**. Bind mounted host directories and files, such as `custom_elasticsearch.yml` above, **need to be accessible by this user**. For the https://www.elastic.co/guide/en/elasticsearch/reference/current/important-settings.html#path-settings[data and log dirs], such as `/usr/share/elasticsearch/data`, write access is required as well. Also see note 1 below.
-
-===== 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}
-COPY --chown=elasticsearch:elasticsearch elasticsearch.yml /usr/share/elasticsearch/config/
---------------------------------------------
-
-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 <various parameters> bin/elasticsearch -Ecluster.name=mynewclustername
---------------------------------------------
-
-==== Notes for production use and defaults
-
-We have collected a number of best practices for production use.
-Any Docker parameters mentioned below assume the use of `docker run`.
-
-. By default, Elasticsearch runs inside the container as user `elasticsearch` using uid:gid `1000:1000`.
-+
-CAUTION: One exception is https://docs.openshift.com/container-platform/3.6/creating_images/guidelines.html#openshift-specific-guidelines[Openshift] which runs containers using an arbitrarily assigned user ID. Openshift will present persistent volumes with the gid set to `0` which will work without any adjustments.
-+
-If you are bind-mounting a local directory or file, ensure it is readable by this user, while the <<path-settings,data and log dirs>> additionally require write access. A good strategy is to grant group access to gid `1000` or `0` for the local directory. As an example, to prepare a local directory for storing data through a bind-mount:
-+
- mkdir esdatadir
- chmod g+rwx esdatadir
- chgrp 1000 esdatadir
-+
-As a last resort, you can also force the container to mutate the ownership of any bind-mounts used for the <<path-settings,data and log dirs>> through the environment variable `TAKE_FILE_OWNERSHIP`; in this case they will be owned by uid:gid `1000:0` providing read/write access to the elasticsearch process as required.
-+
-. It is important to ensure increased ulimits for <<setting-system-settings,nofile>> and <<max-number-threads-check,nproc>> are available for the Elasticsearch containers. Verify the https://github.com/moby/moby/tree/ea4d1243953e6b652082305a9c3cda8656edab26/contrib/init[init system] for the Docker daemon is already setting those to acceptable values and, if needed, adjust them in the Daemon, or override them per container, for example using `docker run`:
-+
- --ulimit nofile=65536:65536
-+
-NOTE: One way of checking the Docker daemon defaults for the aforementioned ulimits is by running:
-+
- docker run --rm centos:7 /bin/bash -c 'ulimit -Hn && ulimit -Sn && ulimit -Hu && ulimit -Su'
-+
-. Swapping needs to be disabled for performance and node stability. This can be
-achieved through any of the methods mentioned in the
-<<setup-configuration-memory,Elasticsearch docs>>. If you opt for the
-`bootstrap.memory_lock: true` approach, apart from defining it through any of
-the <<docker-configuration-methods,configuration methods>>, you will
-additionally need the `memlock: true` ulimit, either defined in the
-https://docs.docker.com/engine/reference/commandline/dockerd/#default-ulimits[Docker
-Daemon] or specifically set for the container. This is demonstrated above in the
-<<docker-prod-cluster-composefile,docker-compose.yml>>. If using `docker run`:
-+
- -e "bootstrap.memory_lock=true" --ulimit memlock=-1:-1
-+
-. 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`.
-+
-. 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 <<docker-cli-run-prod-mode,production example>>, 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, 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[]