[[run-elasticsearch-locally]]
== Run {es} locally in Docker
++++
<titleabbrev>Run {es} locally</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 Elasticsearch in this way in a production environment.
====

Follow this tutorial if you want to quickly set up {es} in Docker for local development or testing.

This tutorial also includes instructions for installing {kib}. 
 If you don't need access to the {kib} UI, then you can skip those instructions.

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

When you access {kib}, use `elastic` as the username and the password you set earlier for the `ELASTIC_PASSWORD` environment variable.

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

[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

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