|
| 1 | +//// |
| 2 | +IMPORTANT: This content is replicated in the Elasticsearch repo root readme. Ensure both files are in sync. |
| 3 | + |
| 4 | +https://github.com/elastic/start-local is the source of truth. |
| 5 | +//// |
| 6 | + |
1 | 7 | [[run-elasticsearch-locally]] |
2 | | -== Run {es} locally in Docker |
| 8 | +== Run {es} locally |
3 | 9 | ++++ |
4 | 10 | <titleabbrev>Run {es} locally</titleabbrev> |
5 | 11 | ++++ |
|
8 | 14 | ==== |
9 | 15 | *DO NOT USE THESE INSTRUCTIONS FOR PRODUCTION DEPLOYMENTS* |
10 | 16 |
|
11 | | -The instructions on this page are for *local development only*. Do not use these instructions for production deployments, because they are not secure. |
12 | | -While this approach is convenient for experimenting and learning, you should never run Elasticsearch in this way in a production environment. |
| 17 | +The instructions on this page are for *local development only*. Do not use this configuration for production deployments, because it is not secure. |
| 18 | +Refer to <<elasticsearch-intro-deploy, deployment options>> for a list of production deployment options. |
13 | 19 | ==== |
14 | 20 |
|
15 | | -Follow this tutorial if you want to quickly set up {es} in Docker for local development or testing. |
| 21 | +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]. |
16 | 22 |
|
17 | | -This tutorial also includes instructions for installing {kib}. |
18 | | - If you don't need access to the {kib} UI, then you can skip those instructions. |
| 23 | +This setup comes with a one-month trial of the Elastic *Platinum* license. |
| 24 | +After the trial period, the license reverts to *Free and open - Basic*. |
| 25 | +Refer to https://www.elastic.co/subscriptions[Elastic subscriptions] for more information. |
19 | 26 |
|
20 | 27 | [discrete] |
21 | 28 | [[local-dev-prerequisites]] |
22 | 29 | === Prerequisites |
23 | 30 |
|
24 | | -If you don't have Docker installed, https://www.docker.com/products/docker-desktop[download and install Docker Desktop] for your operating system. |
| 31 | +- If you don't have Docker installed, https://www.docker.com/products/docker-desktop[download and install Docker Desktop] for your operating system. |
| 32 | +- If you're using Microsoft Windows, then install https://learn.microsoft.com/en-us/windows/wsl/install[Windows Subsystem for Linux (WSL)]. |
25 | 33 |
|
26 | 34 | [discrete] |
27 | | -[[local-dev-env-vars]] |
28 | | -=== Set environment variables |
| 35 | +[[local-dev-quick-start]] |
| 36 | +=== Run `start-local` |
29 | 37 |
|
30 | | -Configure the following environment variables. |
| 38 | +To set up {es} and {kib} locally, run the `start-local` script: |
31 | 39 |
|
32 | 40 | [source,sh] |
33 | 41 | ---- |
34 | | -export ELASTIC_PASSWORD="<ES_PASSWORD>" # password for "elastic" username |
35 | | -export KIBANA_PASSWORD="<KIB_PASSWORD>" # Used _internally_ by Kibana, must be at least 6 characters long |
36 | | ----- |
37 | | - |
38 | | -[discrete] |
39 | | -[[local-dev-create-docker-network]] |
40 | | -=== Create a Docker network |
41 | | - |
42 | | -To run both {es} and {kib}, you'll need to create a Docker network: |
43 | | - |
44 | | -[source,sh] |
45 | | ----- |
46 | | -docker network create elastic-net |
47 | | ----- |
48 | | - |
49 | | -[discrete] |
50 | | -[[local-dev-run-es]] |
51 | | -=== Run {es} |
52 | | - |
53 | | -Start the {es} container with the following command: |
54 | | - |
55 | | -ifeval::["{release-state}"=="unreleased"] |
56 | | -WARNING: Version {version} has not yet been released. |
57 | | -No Docker image is currently available for {es} {version}. |
58 | | -endif::[] |
59 | | - |
60 | | -[source,sh,subs="attributes"] |
61 | | ----- |
62 | | -docker run -p 127.0.0.1:9200:9200 -d --name elasticsearch --network elastic-net \ |
63 | | - -e ELASTIC_PASSWORD=$ELASTIC_PASSWORD \ |
64 | | - -e "discovery.type=single-node" \ |
65 | | - -e "xpack.security.http.ssl.enabled=false" \ |
66 | | - -e "xpack.license.self_generated.type=trial" \ |
67 | | - {docker-image} |
68 | | ----- |
69 | | - |
70 | | -[discrete] |
71 | | -[[local-dev-run-kib]] |
72 | | -=== Run {kib} (optional) |
73 | | - |
74 | | -To run {kib}, you must first set the `kibana_system` password in the {es} container. |
75 | | - |
76 | | -[source,sh,subs="attributes"] |
77 | | ----- |
78 | | -# configure the Kibana password in the ES container |
79 | | -curl -u elastic:$ELASTIC_PASSWORD \ |
80 | | - -X POST \ |
81 | | - http://localhost:9200/_security/user/kibana_system/_password \ |
82 | | - -d '{"password":"'"$KIBANA_PASSWORD"'"}' \ |
83 | | - -H 'Content-Type: application/json' |
| 42 | +curl -fsSL https://elastic.co/start-local | sh |
84 | 43 | ---- |
85 | 44 | // NOTCONSOLE |
86 | 45 |
|
87 | | -Start the {kib} container with the following command: |
| 46 | +This script creates an `elastic-start-local` folder containing configuration files and starts both {es} and {kib} using Docker. |
88 | 47 |
|
89 | | -ifeval::["{release-state}"=="unreleased"] |
90 | | -WARNING: Version {version} has not yet been released. |
91 | | -No Docker image is currently available for {es} {version}. |
92 | | -endif::[] |
| 48 | +After running the script, you can access Elastic services at the following endpoints: |
93 | 49 |
|
94 | | -[source,sh,subs="attributes"] |
95 | | ----- |
96 | | -docker run -p 127.0.0.1:5601:5601 -d --name kibana --network elastic-net \ |
97 | | - -e ELASTICSEARCH_URL=http://elasticsearch:9200 \ |
98 | | - -e ELASTICSEARCH_HOSTS=http://elasticsearch:9200 \ |
99 | | - -e ELASTICSEARCH_USERNAME=kibana_system \ |
100 | | - -e ELASTICSEARCH_PASSWORD=$KIBANA_PASSWORD \ |
101 | | - -e "xpack.security.enabled=false" \ |
102 | | - -e "xpack.license.self_generated.type=trial" \ |
103 | | - {kib-docker-image} |
104 | | ----- |
| 50 | +* *{es}*: http://localhost:9200 |
| 51 | +* *{kib}*: http://localhost:5601 |
105 | 52 |
|
106 | | -When you access {kib}, use `elastic` as the username and the password you set earlier for the `ELASTIC_PASSWORD` environment variable. |
| 53 | +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. |
107 | 54 |
|
108 | | -[NOTE] |
| 55 | +[CAUTION] |
109 | 56 | ==== |
110 | | -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. |
| 57 | +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 through `localhost`. |
111 | 58 | ==== |
112 | 59 |
|
113 | 60 | [discrete] |
114 | | -[[local-dev-connecting-clients]] |
115 | | -=== Connect to {es} with language clients |
116 | | - |
117 | | -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. |
118 | | - |
119 | | -.*Expand* for details |
120 | | -[%collapsible] |
121 | | -============== |
122 | | -
|
123 | | -You'll use the following connection details: |
124 | | -
|
125 | | -* **{es} endpoint**: `http://localhost:9200` |
126 | | -* **Username**: `elastic` |
127 | | -* **Password**: `$ELASTIC_PASSWORD` (Value you set in the environment variable) |
128 | | -
|
129 | | -For example, to connect with the Python `elasticsearch` client: |
130 | | -
|
131 | | -[source,python] |
132 | | ----- |
133 | | -import os |
134 | | -from elasticsearch import Elasticsearch |
| 61 | +[[api-access]] |
| 62 | +=== API access |
135 | 63 |
|
136 | | -username = 'elastic' |
137 | | -password = os.getenv('ELASTIC_PASSWORD') # Value you set in the environment variable |
| 64 | +An API key for {es} is generated and stored in the `.env` file as `ES_LOCAL_API_KEY`. |
| 65 | +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>>. |
138 | 66 |
|
139 | | -client = Elasticsearch( |
140 | | - "http://localhost:9200", |
141 | | - basic_auth=(username, password) |
142 | | -) |
| 67 | +From the `elastic-start-local` folder, check the connection to Elasticsearch using `curl`: |
143 | 68 |
|
144 | | -print(client.info()) |
145 | | ----- |
146 | | -
|
147 | | -Here's an example curl command using basic authentication: |
148 | | -
|
149 | | -[source,sh,subs="attributes"] |
150 | | ----- |
151 | | -curl -u elastic:$ELASTIC_PASSWORD \ |
152 | | - -X PUT \ |
153 | | - http://localhost:9200/my-new-index \ |
154 | | - -H 'Content-Type: application/json' |
| 69 | +[source,sh] |
| 70 | +---- |
| 71 | +source .env |
| 72 | +curl $ES_LOCAL_URL -H "Authorization: ApiKey ${ES_LOCAL_API_KEY}" |
155 | 73 | ---- |
156 | 74 | // NOTCONSOLE |
157 | 75 |
|
158 | | -============== |
159 | | - |
160 | 76 | [discrete] |
161 | | -[[local-dev-next-steps]] |
162 | | -=== Next steps |
| 77 | +[[local-dev-additional-info]] |
| 78 | +=== Learn more |
163 | 79 |
|
164 | | -Use our <<quickstart,quick start guides>> to learn the basics of {es}. |
| 80 | +For more detailed information about the `start-local` setup, refer to the https://github.com/elastic/start-local[README on GitHub]. |
| 81 | +Learn about customizing the setup, logging, and more. |
165 | 82 |
|
166 | 83 | [discrete] |
167 | | -[[local-dev-production]] |
168 | | -=== Moving to production |
| 84 | +[[local-dev-next-steps]] |
| 85 | +=== Next steps |
169 | 86 |
|
170 | | -This setup is not suitable for production use. |
171 | | -Refer to <<elasticsearch-intro-deploy, deployment options>> for more information. |
| 87 | +Use our <<quickstart,quick start guides>> to learn the basics of {es}. |
0 commit comments