elastic · elasticsearchmachine · Oct 2, 2024 · Oct 1, 2024 · Oct 1, 2024 · Oct 1, 2024
diff --git a/README.asciidoc b/README.asciidoc
@@ -33,9 +33,11 @@ https://www.elastic.co/downloads/elasticsearch[elastic.co/downloads/elasticsearc
 === Run Elasticsearch locally
 
 //// 
-IMPORTANT: This content is replicated in the Elasticsearch guide. See `run-elasticsearch-locally.asciidoc`.
-Both will soon be replaced by a quickstart script.
-////
+IMPORTANT: This content is replicated in the Elasticsearch repo. See `run-elasticsearch-locally.asciidoc`.
+Ensure both files are in sync.
+
+https://github.com/elastic/start-local is the source of truth.
+//// 
 
 [WARNING]
 ==== 
@@ -44,81 +46,58 @@ DO NOT USE THESE INSTRUCTIONS FOR PRODUCTION DEPLOYMENTS.
 This setup is intended for local development and testing only.
 ====
 
-The following commands help you very quickly spin up a single-node Elasticsearch cluster, together with Kibana in Docker.
-Use this setup for local development or testing.
+Quickly set up Elasticsearch and Kibana in Docker for local development or testing, using the https://github.com/elastic/start-local?tab=readme-ov-file#-try-elasticsearch-and-kibana-locally[`start-local` script].
 
 ==== Prerequisites
 
 If you don't have Docker installed, https://www.docker.com/products/docker-desktop[download and install Docker Desktop] for your operating system.
 
-==== Set environment variables
-
-Configure the following environment variables.
+==== Trial license
 
-[source,sh]
-----
-export ELASTIC_PASSWORD="<ES_PASSWORD>"  # password for "elastic" username
-export KIBANA_PASSWORD="<KIB_PASSWORD>"   # Used internally by Kibana, must be at least 6 characters long
-----
+This setup comes with a one-month trial of the Elastic *Platinum* license.
+After the trial period, the license reverts to *Free and open - Basic*.
+Refer to https://www.elastic.co/subscriptions[Elastic subscriptions] for more information.
 
-==== Create a Docker network
+=== Run `start-local`
 
-To run both Elasticsearch and Kibana, you'll need to create a Docker network:
+To set up Elasticsearch and Kibana locally, run the `start-local` script:
 
 [source,sh]
 ----
-docker network create elastic-net
+curl -fsSL https://elastic.co/start-local | sh
 ----
+// NOTCONSOLE
 
-==== Run Elasticsearch
-
-Start the Elasticsearch container with the following command:
+This script creates an `elastic-start-local` folder containing configuration files and starts both Elasticsearch and Kibana using Docker.
 
-[source,sh]
-----
-docker run -p 127.0.0.1:9200:9200 -d --name elasticsearch --network elastic-net \
-  -e ELASTIC_PASSWORD=$ELASTIC_PASSWORD \
-  -e "discovery.type=single-node" \
-  -e "xpack.security.http.ssl.enabled=false" \
-  -e "xpack.license.self_generated.type=trial" \
-  docker.elastic.co/elasticsearch/elasticsearch:{version}
-----
+After running the script:
 
-==== Run Kibana (optional)
+* *Elasticsearch* will be running at http://localhost:9200
+* *Kibana* will be running at http://localhost:5601
 
-To run Kibana, you must first set the `kibana_system` password in the Elasticsearch container.
+Check the connection to Elasticsearch using `curl` in the `elastic-start-local` folder:
 
 [source,sh]
-----
-# configure the Kibana password in the ES container
-curl -u elastic:$ELASTIC_PASSWORD \
-  -X POST \
-  http://localhost:9200/_security/user/kibana_system/_password \
-  -d '{"password":"'"$KIBANA_PASSWORD"'"}' \
-  -H 'Content-Type: application/json'
+----     
+source .env
+curl $ES_LOCAL_URL -H "Authorization: ApiKey ${ES_LOCAL_API_KEY}"
 ----
 // NOTCONSOLE
 
-Start the Kibana container with the following command:
-
-[source,sh]
-----
-docker run -p 127.0.0.1:5601:5601 -d --name kibana --network elastic-net \
-  -e ELASTICSEARCH_URL=http://elasticsearch:9200 \
-  -e ELASTICSEARCH_HOSTS=http://elasticsearch:9200 \
-  -e ELASTICSEARCH_USERNAME=kibana_system \
-  -e ELASTICSEARCH_PASSWORD=$KIBANA_PASSWORD \
-  -e "xpack.security.enabled=false" \
-  -e "xpack.license.self_generated.type=trial" \
-  docker.elastic.co/kibana/kibana:{version}
-----
-
-.Trial license
-[%collapsible]
+[CAUTION]
 ====
-The service is started with a trial license. The trial license enables all features of Elasticsearch for a trial period of 30 days. After the trial period expires, the license is downgraded to a basic license, which is free forever. If you prefer to skip the trial and use the basic license, set the value of the `xpack.license.self_generated.type` variable to basic instead. For a detailed feature comparison between the different licenses, refer to our https://www.elastic.co/subscriptions[subscriptions page].
+This setup is for local testing only. HTTPS is disabled, and Basic authentication is used for Elasticsearch. For security, Elasticsearch and Kibana are accessible only via `localhost`.
 ====
 
+==== Authentication
+
+The script generates a random password for the `elastic` user, which is displayed at the end of the installation and stored in the `.env` file.
+
+An API key for Elasticsearch is generated and stored in the `.env` file as `ES_LOCAL_API_KEY`.
+Use this key to connect to Elasticsearch with a https://www.elastic.co/guide/en/elasticsearch/client/index.html[programming language client] or the https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html[REST API].
+
+ℹ️ For more detailed information about the `start-local` setup refer to the https://github.com/elastic/start-local[README on GitHub].
+
 ==== Send requests to Elasticsearch
 
 You send data and other requests to Elasticsearch through REST APIs. 

diff --git a/docs/reference/run-elasticsearch-locally.asciidoc b/docs/reference/run-elasticsearch-locally.asciidoc
@@ -1,5 +1,11 @@
+//// 
+IMPORTANT: This content is replicated in the Elasticsearch repo root readme. Ensure both files are in sync.
+
+https://github.com/elastic/start-local is the source of truth.        
+//// 
+
 [[run-elasticsearch-locally]]
-== Run {es} locally in Docker
+== Run {es} locally
 ++++
 <titleabbrev>Run {es} locally</titleabbrev>
 ++++
@@ -9,163 +15,75 @@
 *DO NOT USE THESE INSTRUCTIONS FOR PRODUCTION DEPLOYMENTS*
 
 The instructions on this page are for *local development only*. Do not use these instructions for production deployments, because they are not secure.
-While this approach is convenient for experimenting and learning, you should never run Elasticsearch in this way in a production environment.
+Refer to <<elasticsearch-intro-deploy, deployment options>> for a list of production deployment options.
 ====
 
-Follow this tutorial if you want to quickly set up {es} in Docker for local development or testing.
+Quickly set up {es} and {kib} in Docker for local development or testing, using the https://github.com/elastic/start-local?tab=readme-ov-file#-try-elasticsearch-and-kibana-locally[`start-local` script].
 
-This tutorial also includes instructions for installing {kib}. 
- If you don't need access to the {kib} UI, then you can skip those instructions.
+This setup comes with a one-month trial of the Elastic *Platinum* license.
+After the trial period, the license reverts to *Free and open - Basic*.
+Refer to https://www.elastic.co/subscriptions[Elastic subscriptions] for more information.
 
 [discrete]
 [[local-dev-prerequisites]]
 === Prerequisites
 
 If you don't have Docker installed, https://www.docker.com/products/docker-desktop[download and install Docker Desktop] for your operating system.
 
-[discrete]
-[[local-dev-env-vars]]
-=== Set environment variables
-
-Configure the following environment variables.
-
-[source,sh]
-----
-export ELASTIC_PASSWORD="<ES_PASSWORD>"  # password for "elastic" username
-export KIBANA_PASSWORD="<KIB_PASSWORD>"   # Used _internally_ by Kibana, must be at least 6 characters long
-----
+- Works on Linux and macOS
+- Works on Microsoft Windows using https://learn.microsoft.com/en-us/windows/wsl/install[Windows Subsystem for Linux (WSL)]
 
 [discrete]
-[[local-dev-create-docker-network]]
-=== Create a Docker network
+[[local-dev-quick-start]]
+=== Run `start-local`
 
-To run both {es} and {kib}, you'll need to create a Docker network:
+To set up {es} and {kib} locally, run the `start-local` script:
 
 [source,sh]
 ----
-docker network create elastic-net
+curl -fsSL https://elastic.co/start-local | sh
 ----
+// NOTCONSOLE
 
-[discrete]
-[[local-dev-run-es]]
-=== Run {es}
-
-Start the {es} container with the following command:
+This script creates an `elastic-start-local` folder containing configuration files and starts both {es} and {kib} using Docker.
 
-ifeval::["{release-state}"=="unreleased"]
-WARNING: Version {version} has not yet been released.
-No Docker image is currently available for {es} {version}.
-endif::[]
+After running the script:
 
-[source,sh,subs="attributes"]
-----
-docker run -p 127.0.0.1:9200:9200 -d --name elasticsearch --network elastic-net \
-  -e ELASTIC_PASSWORD=$ELASTIC_PASSWORD \
-  -e "discovery.type=single-node" \
-  -e "xpack.security.http.ssl.enabled=false" \
-  -e "xpack.license.self_generated.type=trial" \
-  {docker-image}
-----
-
-[discrete]
-[[local-dev-run-kib]]
-=== Run {kib} (optional)
+* *{es}* will be running at http://localhost:9200
+* *{kib}* will be running at http://localhost:5601
 
-To run {kib}, you must first set the `kibana_system` password in the {es} container.
+Check the connection to Elasticsearch using `curl` in the `elastic-start-local` folder:
 
-[source,sh,subs="attributes"]
-----
-# configure the Kibana password in the ES container
-curl -u elastic:$ELASTIC_PASSWORD \
-  -X POST \
-  http://localhost:9200/_security/user/kibana_system/_password \
-  -d '{"password":"'"$KIBANA_PASSWORD"'"}' \
-  -H 'Content-Type: application/json'
+[source,sh]
+----     
+source .env
+curl $ES_LOCAL_URL -H "Authorization: ApiKey ${ES_LOCAL_API_KEY}"
 ----
 // NOTCONSOLE
 
-Start the {kib} container with the following command:
-
-ifeval::["{release-state}"=="unreleased"]
-WARNING: Version {version} has not yet been released.
-No Docker image is currently available for {es} {version}.
-endif::[]
-
-[source,sh,subs="attributes"]
-----
-docker run -p 127.0.0.1:5601:5601 -d --name kibana --network elastic-net \
-  -e ELASTICSEARCH_URL=http://elasticsearch:9200 \
-  -e ELASTICSEARCH_HOSTS=http://elasticsearch:9200 \
-  -e ELASTICSEARCH_USERNAME=kibana_system \
-  -e ELASTICSEARCH_PASSWORD=$KIBANA_PASSWORD \
-  -e "xpack.security.enabled=false" \
-  -e "xpack.license.self_generated.type=trial" \
-  {kib-docker-image}
-----
-
-When you access {kib}, use `elastic` as the username and the password you set earlier for the `ELASTIC_PASSWORD` environment variable.
-
-[NOTE]
+[CAUTION]
 ====
-The service is started with a trial license. The trial license enables all features of Elasticsearch for a trial period of 30 days. After the trial period expires, the license is downgraded to a basic license, which is free forever.
+This setup is for local testing only. HTTPS is disabled, and Basic authentication is used for {es}. For security, {es} and {kib} are accessible only via `localhost`.
 ====
 
 [discrete]
-[[local-dev-connecting-clients]]
-=== Connect to {es} with language clients
-
-To connect to the {es} cluster from a language client, you can use basic authentication with the `elastic` username and the password you set in the environment variable.
-
-.*Expand* for details
-[%collapsible]
-==============
-
-You'll use the following connection details:
-
-* **{es} endpoint**: `http://localhost:9200`
-* **Username**: `elastic`
-* **Password**: `$ELASTIC_PASSWORD` (Value you set in the environment variable)
-
-For example, to connect with the Python `elasticsearch` client:
-
-[source,python]
-----
-import os
-from elasticsearch import Elasticsearch
+[[local-dev-authentication]]
+=== Authentication
 
-username = 'elastic'
-password = os.getenv('ELASTIC_PASSWORD') # Value you set in the environment variable
+The script generates a random password for the `elastic` user, which is displayed at the end of the installation and stored in the `.env` file.
 
-client = Elasticsearch(
-    "http://localhost:9200",
-    basic_auth=(username, password)
-)
+An API key for {es} is generated and stored in the `.env` file as `ES_LOCAL_API_KEY`.
+Use this key to connect to {es} with a https://www.elastic.co/guide/en/elasticsearch/client/index.html[programming language client] or the <<rest-apis,REST API>>.
 
-print(client.info())
-----
-
-Here's an example curl command using basic authentication:
-
-[source,sh,subs="attributes"]
-----
-curl -u elastic:$ELASTIC_PASSWORD \
-  -X PUT \
-  http://localhost:9200/my-new-index \
-  -H 'Content-Type: application/json'
-----
-// NOTCONSOLE
+[discrete]
+[[local-dev-additional-info]]
+=== Additional information
 
-==============
+For more detailed information about the `start-local` setup refer to the https://github.com/elastic/start-local[README on GitHub].
+Learn about customizing the setup, logging, and more.
 
 [discrete]
 [[local-dev-next-steps]]
 === Next steps
 
-Use our <<quickstart,quick start guides>> to learn the basics of {es}.
-
-[discrete]
-[[local-dev-production]]
-=== Moving to production
-
-This setup is not suitable for production use.
-Refer to <<elasticsearch-intro-deploy, deployment options>> for more information.
+Use our <<quickstart,quick start guides>> to learn the basics of {es}.