|
@@ -1,10 +1,9 @@
|
|
|
[[docker]]
|
|
|
=== Install {es} with Docker
|
|
|
|
|
|
-{es} is also available as Docker images. A list of all published Docker
|
|
|
-images and tags is available at
|
|
|
-https://www.docker.elastic.co[www.docker.elastic.co]. The source files are
|
|
|
-in
|
|
|
+{es} is available as a Docker image. A list of all published Docker images and
|
|
|
+tags is available at https://www.docker.elastic.co[www.docker.elastic.co]. The
|
|
|
+source files are in
|
|
|
https://github.com/elastic/elasticsearch/blob/{branch}/distribution/docker[Github].
|
|
|
|
|
|
include::license.asciidoc[]
|
|
@@ -13,19 +12,19 @@ Starting in {es} 8.0, security is enabled by default. With security enabled,
|
|
|
{stack} {security-features} require TLS encryption for the transport networking
|
|
|
layer, or your cluster will fail to start.
|
|
|
|
|
|
-==== Install Docker Desktop or Docker Engine
|
|
|
+==== Install Docker
|
|
|
|
|
|
-Install the appropriate https://docs.docker.com/get-docker/[Docker application]
|
|
|
-for your operating system.
|
|
|
+Visit https://docs.docker.com/get-docker/[Get Docker] to install Docker for your
|
|
|
+environment.
|
|
|
|
|
|
-NOTE: Make sure that Docker is allotted at least 4GiB of memory. In Docker
|
|
|
-Desktop, you configure resource usage on the Advanced tab in Preference (macOS)
|
|
|
-or Settings (Windows).
|
|
|
+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**.
|
|
|
|
|
|
-==== Pull the {es} Docker image
|
|
|
+==== Pull the Docker image
|
|
|
|
|
|
-Obtaining {es} for Docker is as simple as issuing a `docker pull` command
|
|
|
-against the Elastic Docker registry.
|
|
|
+Use the `docker pull` command to pull the {es} image from the the Elastic Docker
|
|
|
+registry.
|
|
|
|
|
|
ifeval::["{release-state}"=="unreleased"]
|
|
|
|
|
@@ -44,12 +43,11 @@ docker pull {docker-repo}:{version}
|
|
|
endif::[]
|
|
|
|
|
|
[[docker-verify-signature]]
|
|
|
-==== Optional: Verify the {es} Docker image signature
|
|
|
+==== Optional: Verify the image signature
|
|
|
|
|
|
-Although it's optional, we highly recommend verifying the signatures included with your downloaded Docker images to ensure that the images are valid.
|
|
|
+Verify the signatures included in your {es} Docker images to ensure they're valid.
|
|
|
|
|
|
Elastic images are signed with https://docs.sigstore.dev/cosign/overview/[Cosign] which is part of the https://www.sigstore.dev/[Sigstore] project.
|
|
|
-
|
|
|
Cosign supports container signing, verification, and storage in an OCI registry.
|
|
|
|
|
|
ifeval::["{release-state}"=="unreleased"]
|
|
@@ -76,7 +74,7 @@ cosign verify --key cosign.pub {docker-repo}:{version} <2>
|
|
|
|
|
|
The command prints the check results and the signature payload in JSON format:
|
|
|
|
|
|
-[source,sh]
|
|
|
+[source,sh,subs="attributes"]
|
|
|
--------------------------------------------
|
|
|
Verification for docker.elastic.co/elasticsearch/elasticsearch:{version} --
|
|
|
The following checks were performed on each of these signatures:
|
|
@@ -87,47 +85,35 @@ The following checks were performed on each of these signatures:
|
|
|
|
|
|
endif::[]
|
|
|
|
|
|
-Now that you have verified the {es} Docker image signature, you can start a
|
|
|
-<<docker-cli-run-dev-mode,single-node>> or <<docker-compose-file,multi-node>>
|
|
|
-cluster.
|
|
|
|
|
|
[[docker-cli-run-dev-mode]]
|
|
|
-==== Start a single-node cluster with Docker
|
|
|
+==== Run {es} in Docker
|
|
|
|
|
|
-ifeval::["{release-state}"=="unreleased"]
|
|
|
+Use Docker commands to start a single-node {es} cluster for development or
|
|
|
+testing. You can then run additional Docker commands to add nodes to the test
|
|
|
+cluster.
|
|
|
|
|
|
-WARNING: Version {version} of the {es} Docker image has not yet been released.
|
|
|
+TIP: This setup doesn't run multiple {es} nodes or {kib} by default. To create a
|
|
|
+multi-node cluster with {kib}, use Docker Compose instead. See
|
|
|
+<<docker-compose-file>>.
|
|
|
|
|
|
-endif::[]
|
|
|
|
|
|
-If you're starting a single-node {es} cluster in a Docker container, security
|
|
|
-will be automatically enabled and configured for you. When you start {es} for
|
|
|
-the first time, the following security configuration occurs automatically:
|
|
|
+===== Start a single-node cluster
|
|
|
|
|
|
-* <<elasticsearch-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}.
|
|
|
+ifeval::["{release-state}"=="unreleased"]
|
|
|
|
|
|
-You can then {kibana-ref}/docker.html[start {kib}] and enter the enrollment
|
|
|
-token, which is valid for 30 minutes. This token automatically applies the
|
|
|
-security settings from your {es} cluster, authenticates to {es} with the
|
|
|
-`kibana_system` user, and writes the security configuration to `kibana.yml`.
|
|
|
+WARNING: Version {version} of the {es} Docker image has not yet been released.
|
|
|
|
|
|
-The following commands start a single-node {es} cluster for development or
|
|
|
-testing.
|
|
|
+endif::[]
|
|
|
|
|
|
-. Create a new docker network for {es} and {kib}
|
|
|
+. Create a new docker network.
|
|
|
+
|
|
|
[source,sh]
|
|
|
----
|
|
|
docker network create elastic
|
|
|
----
|
|
|
|
|
|
-. Start {es} in Docker. A password is generated for the `elastic` user and
|
|
|
-output to the terminal, plus an enrollment token for enrolling {kib}.
|
|
|
+. Start an {es} container.
|
|
|
+
|
|
|
--
|
|
|
ifeval::["{release-state}"=="unreleased"]
|
|
@@ -140,78 +126,64 @@ endif::[]
|
|
|
ifeval::["{release-state}"!="unreleased"]
|
|
|
[source,sh,subs="attributes"]
|
|
|
----
|
|
|
-docker run --name es01 --net elastic -p 9200:9200 -it {docker-image}
|
|
|
+docker run --name es01 --net elastic -p 9200:9200 -it -m 1GB {docker-image}
|
|
|
----
|
|
|
|
|
|
+TIP: Use the `-m` flag to set a memory limit for the container.
|
|
|
+
|
|
|
+The command prints the `elastic` user password and an enrollment token for {kib}.
|
|
|
+
|
|
|
endif::[]
|
|
|
--
|
|
|
-+
|
|
|
-TIP: 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.
|
|
|
+. 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.
|
|
|
+
|
|
|
-[NOTE]
|
|
|
-====
|
|
|
-If you need to reset the password for the `elastic` user or other
|
|
|
-built-in users, run the <<reset-password,`elasticsearch-reset-password`>> tool.
|
|
|
-This tool is available in the {es} `/bin` directory of the Docker container.
|
|
|
-For example:
|
|
|
+--
|
|
|
+[source,sh,subs="attributes"]
|
|
|
+----
|
|
|
+docker exec -it es01 /usr/share/elasticsearch/bin/elasticsearch-reset-password
|
|
|
+docker exec -it es01 /usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s kibana
|
|
|
+----
|
|
|
+
|
|
|
+We recommend storing the `elastic` password as an environment variable in your shell. Example:
|
|
|
|
|
|
[source,sh]
|
|
|
----
|
|
|
-docker exec -it es01 /usr/share/elasticsearch/bin/elasticsearch-reset-password
|
|
|
+export ELASTIC_PASSWORD="your_password"
|
|
|
----
|
|
|
-====
|
|
|
+--
|
|
|
|
|
|
-. Copy the `http_ca.crt` security certificate from your Docker container to
|
|
|
-your local machine.
|
|
|
+. Copy the `http_ca.crt` SSL certificate from the container to your local machine.
|
|
|
+
|
|
|
[source,sh]
|
|
|
----
|
|
|
docker cp es01:/usr/share/elasticsearch/config/certs/http_ca.crt .
|
|
|
----
|
|
|
|
|
|
-. Open a new terminal and verify that you can connect to your {es} cluster by
|
|
|
-making an authenticated call, using the `http_ca.crt` file that you copied from
|
|
|
-your Docker container. Enter the password for the `elastic` user when prompted.
|
|
|
+. Make a REST API call to {es} to ensure the {es} container is running.
|
|
|
+
|
|
|
[source,sh]
|
|
|
----
|
|
|
-curl --cacert http_ca.crt -u elastic https://localhost:9200
|
|
|
+curl --cacert http_ca.crt -u elastic:$ELASTIC_PASSWORD https://localhost:9200
|
|
|
----
|
|
|
// NOTCONSOLE
|
|
|
|
|
|
-==== Enroll additional nodes
|
|
|
-
|
|
|
-When you start {es} for the first time, the installation process configures a single-node cluster by default. This process also generates an enrollment token
|
|
|
-and prints it to your terminal. If you want a node to join an existing cluster,
|
|
|
-start the new node with the generated enrollment token.
|
|
|
+===== Add more nodes
|
|
|
|
|
|
+. Use an existing node to generate a enrollment token for the new node.
|
|
|
++
|
|
|
--
|
|
|
-.Generating enrollment tokens
|
|
|
-****
|
|
|
-The enrollment token is valid for 30 minutes. If you need to generate a
|
|
|
-new enrollment token, run the
|
|
|
-<<create-enrollment-token,`elasticsearch-create-enrollment-token`>> tool on your
|
|
|
-existing node. This tool is available in the {es} `bin` directory of the Docker
|
|
|
-container.
|
|
|
-
|
|
|
-For example, run the following command on the existing `es01` node to
|
|
|
-generate an enrollment token for new {es} nodes:
|
|
|
-
|
|
|
[source,sh]
|
|
|
----
|
|
|
docker exec -it es01 /usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s node
|
|
|
----
|
|
|
-****
|
|
|
---
|
|
|
|
|
|
-. In the terminal where you started your first node, copy the generated
|
|
|
-enrollment token for adding new {es} nodes.
|
|
|
+The enrollment token is valid for 30 minutes.
|
|
|
+--
|
|
|
|
|
|
-. On your new node, start {es} and include the generated enrollment token.
|
|
|
+. Start a new {es} container. Include the enrollment token as an environment variable.
|
|
|
+
|
|
|
--
|
|
|
ifeval::["{release-state}"=="unreleased"]
|
|
@@ -228,10 +200,16 @@ docker run -e ENROLLMENT_TOKEN="<token>" --name es02 --net elastic -it {docker-i
|
|
|
----
|
|
|
|
|
|
endif::[]
|
|
|
-
|
|
|
-{es} is now configured to join the existing cluster.
|
|
|
--
|
|
|
|
|
|
+. Call the <<cat-nodes,cat nodes API>> to verify the node was added to the cluster.
|
|
|
++
|
|
|
+[source,sh]
|
|
|
+----
|
|
|
+curl --cacert http_ca.crt -u elastic:$ELASTIC_PASSWORD https://localhost:9200/_cat/nodes
|
|
|
+----
|
|
|
+// NOTCONSOLE
|
|
|
+
|
|
|
===== Setting JVM heap size
|
|
|
If you experience issues where the container where your first node is running
|
|
|
exits when your second node starts, explicitly set values for the JVM heap size.
|