[[run-elasticsearch-locally]]
== Run {es} locally in Docker (without security)
++++
<titleabbrev>Local dev setup (Docker)</titleabbrev>
++++

[WARNING]
====
*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 the service in this way in a production environment.

Refer to https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html[Install {es}] to learn about the various options for installing {es} in a production environment, including using Docker.
====

The following commands help you very quickly spin up a single-node {es} cluster, together with {kib} in Docker.
Note that if you don't need the {kib} UI, you can skip those instructions.

[discrete]
[[local-dev-why]]
=== When would I use this setup?

Use this setup if you want to quickly spin up {es} (and {kib}) for local development or testing.

For example you might:

* Want to run a quick test to see how a feature works.
* Follow a tutorial or guide that requires an {es} cluster, like our <<getting-started,quick start guide>>.
* Experiment with the {es} APIs using different tools, like the Dev Tools Console, cURL, or an Elastic programming language client.
* Quickly spin up an {es} cluster to test an executable https://github.com/elastic/elasticsearch-labs/tree/main/notebooks#readme[Python notebook] locally.

[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
----

[discrete]
[[local-dev-create-docker-network]]
=== Create a Docker network

To run both {es} and {kib}, you'll need to create a Docker network:

[source,sh]
----
docker network create elastic-net
----

[discrete]
[[local-dev-run-es]]
=== Run {es}

Start the {es} 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: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)

To run {kib}, you must first set the `kibana_system` password in the {es} container.

[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'
----
// 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}
----

[NOTE]
====
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].
====

[discrete]
[[local-dev-connecting-clients]]
== Connecting 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.

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

username = 'elastic'
password = os.getenv('ELASTIC_PASSWORD') # Value you set in the environment variable

client = Elasticsearch(
    "http://localhost:9200",
    basic_auth=(username, password)
)

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-next-steps]]
=== Next steps

Use our <<getting-started,quick start guide>> to learn the basics of {es}: how to add data and query it.

[discrete]
[[local-dev-production]]
=== Moving to production

This setup is not suitable for production use. For production deployments, we recommend using our managed service on Elastic Cloud. https://cloud.elastic.co/registration[Sign up for a free trial] (no credit card required).

Otherwise, refer to https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html[Install {es}] to learn about the various options for installing {es} in a self-managed production environment, including using Docker.