[8.9] [DOCS] Simplify single-node Docker instructions (#98886) (#98937)

Author: jrodewig

docs/reference/setup/install/docker.asciidoc

@@ -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.