Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 43 ยท Getting Started

Setup and Your First Requests

Run Elasticsearch locally with Docker, understand its security defaults, send REST requests with curl and Kibana Dev Tools, and read cluster health.

Elasticsearch speaks HTTP. Once a node is running, everything you do (creating an index, adding a document, searching, checking health) is an HTTP request with a method, a path and, usually, a JSON body. There is no special client you must install to start, and that makes the first steps easy to learn.

Because the server cannot run on this site, the commands and requests in this lesson are read-only. To practise anyway, you will build a small JavaScript mock of the REST API: a function that takes a method, a path and a JSON body and returns a JSON answer shaped like Elasticsearch's. It is a teaching model, not the real engine, and later lessons reuse its ideas.

Running Elasticsearch with Docker

Docker is the quickest way to try Elasticsearch on your own machine. A typical single-node development setup looks like this (read-only; check the official install page for the current image tag):

Terminal
docker network create elastic

docker run --name es01 --net elastic \
  -p 9200:9200 -m 2GB \
  -e "discovery.type=single-node" \
  docker.elastic.co/elasticsearch/elasticsearch:9.0.0

On first start, the container prints a generated password for the built-in elastic user and an enrollment token for Kibana. Copy the password, because it is shown only once; you can reset it later with the elasticsearch-reset-password tool inside the container.

Two details matter:

  • Memory. Elasticsearch runs on the JVM. Give the container at least 1-2 GB for experiments. In production the heap is usually set to about half of the machine's RAM, up to roughly 30 GB.
  • discovery.type=single-node tells the node not to look for other nodes to form a cluster. It is for development only.

Linux hosts running Elasticsearch may also need the kernel setting vm.max_map_count raised to at least 262144; Docker Desktop on Windows and macOS usually handles this for you.

Installing without Docker

Docker is convenient, but production clusters usually run from packages. All of these are read-only here; follow the official install page for the exact version and checksums.

Platform Typical route
Linux (Debian/Ubuntu) add Elastic's APT repository, then apt install elasticsearch; managed by systemd
Linux (RHEL/Fedora) the YUM/DNF repository or the RPM package
Any Linux, macOS download the .tar.gz, unpack it and run bin/elasticsearch
Windows download the .zip, unpack it and run bin\elasticsearch.bat, or install it as a Windows service with elasticsearch-service.bat
Kubernetes the Elastic Cloud on Kubernetes operator
Terminal
# archive install on Linux or macOS
tar -xzf elasticsearch-9.0.0-linux-x86_64.tar.gz
cd elasticsearch-9.0.0
./bin/elasticsearch          # prints the elastic password on first start

The directories matter: config/ holds elasticsearch.yml, jvm.options and the security files, data/ holds your indexes, and logs/ holds the logs. With a package install they live under /etc/elasticsearch, /var/lib/elasticsearch and /var/log/elasticsearch. Back up data only through snapshots, never by copying files while the node runs.

Heap, memory maps and bootstrap checks

Two settings cause most "it will not start in production" problems.

JVM heap. Elasticsearch sizes its heap automatically from the machine's memory, which is right for most nodes. If you override it, put a file in config/jvm.options.d/, set minimum and maximum to the same value, and stay at or below about half of RAM and below roughly 30 GB. The other half is not wasted: Lucene relies on the operating system's file cache for fast reads.

TEXT
# config/jvm.options.d/heap.options
-Xms8g
-Xmx8g

Memory maps. Elasticsearch memory-maps index files, so Linux must allow many mappings:

Terminal
sudo sysctl -w vm.max_map_count=262144
# make it permanent in /etc/sysctl.d/99-elasticsearch.conf

Once a node is configured to listen on a non-loopback address, Elasticsearch runs bootstrap checks at startup and refuses to start if one fails. They include the heap minimum equal to the maximum, vm.max_map_count, file descriptor limits (at least 65535), the maximum thread count and a check that swapping is disabled or locked. A failing check is a feature: it stops a node that would misbehave under load. Single-node development setups skip them.

From one node to several

To form a cluster, give each node a cluster name, a node name, a reachable address and a list of seed hosts. For the very first start, name the initial master-eligible nodes:

YAML
cluster.name: shop-prod
node.name: es-1
network.host: 10.0.1.11
discovery.seed_hosts: [ "10.0.1.11", "10.0.1.12", "10.0.1.13" ]
cluster.initial_master_nodes: [ "es-1", "es-2", "es-3" ]   # first bootstrap only

Remove cluster.initial_master_nodes once the cluster has formed. In recent versions, the enrollment-token workflow (elasticsearch-create-enrollment-token) lets a new node join and fetch the TLS material automatically.

Firewalls and ports

  • 9200 is the HTTP API for clients. Open it only to your application servers and to Kibana.
  • 9300 is the transport port for node-to-node traffic. Open it only between cluster nodes.

Never publish either port to the internet. Pair the firewall with the security layers described in Security, Backups and Operations.

Security is on by default

Since version 8, security is enabled automatically on a new install:

  • the HTTP API uses HTTPS with a self-signed certificate that the node generates;
  • every request needs credentials: a username and password, or an API key;
  • the cluster nodes talk to each other over encrypted transport.

So http://localhost:9200 does not work on a fresh node: you need https:// and a login. Copy the certificate out of the container once, and pass it to curl:

Terminal
docker cp es01:/usr/share/elasticsearch/config/certs/http_ca.crt .

curl --cacert http_ca.crt -u elastic:$ELASTIC_PASSWORD https://localhost:9200

The answer is a small JSON document:

JSON
{
  "name": "es01",
  "cluster_name": "docker-cluster",
  "version": {
    "number": "9.0.0",
    "lucene_version": "10.1.0"
  },
  "tagline": "You Know, for Search"
}

(The exact values depend on your version.) Some tutorials switch security off with xpack.security.enabled=false for convenience. That is acceptable on a throwaway laptop container and dangerous anywhere reachable from a network.

Sending requests

You can talk to Elasticsearch in three common ways.

curl works from any terminal. For a request with a body, set the content type:

Terminal
curl --cacert http_ca.crt -u elastic:$ELASTIC_PASSWORD \
  -X PUT "https://localhost:9200/notes/_doc/1" \
  -H "Content-Type: application/json" \
  -d '{"title": "First note", "done": false}'

Kibana Dev Tools is a console in the browser (Kibana starts on port 5601). It lets you write requests in a shorter form, without host, certificate or headers, and it handles authentication for you:

JSON
PUT /notes/_doc/1
{
  "title": "First note",
  "done": false
}

Almost every example in this tutorial uses this console format: method, path, optional JSON body.

Official clients exist for JavaScript, Python, PHP, Java, Go, .NET and Ruby. They build the same HTTP requests for you (see Using Elasticsearch from Code). For an API key, clients and curl send a header like Authorization: ApiKey <encoded key>.

The shape of the REST API

The paths follow a small set of patterns:

Request Meaning
GET / Basic node and version info
GET /_cluster/health Cluster health
PUT /notes Create an index named notes
PUT /notes/_doc/1 Create or replace document 1
GET /notes/_doc/1 Fetch document 1
GET /notes/_search Search the index
DELETE /notes Delete the whole index (careful)

Names that start with an underscore (_doc, _search, _cluster) are API endpoints, not user data. Index names must be lowercase.

From zero to first search

Start a node Docker image, one command.
Log in HTTPS plus the elastic password.
Send JSON Method, path and body.
Check health Green, yellow or red.

Every later lesson is built on these four steps.

1 / 2

API conventions

Every Elasticsearch endpoint follows the same rules, so once you know them you can guess most requests.

Targets. Where an index name is expected you can usually give several: a comma-separated list (logs-a,logs-b), a wildcard (logs-*), an exclusion (logs-*,-logs-old) or _all. The same applies to aliases and data streams. Options such as ignore_unavailable, allow_no_indices and expand_wildcards decide what happens when a name matches nothing (Multi-Index Search).

Date math in index names. Put a date expression in angle brackets to build a name from the clock, and URL-encode it when it sits in a path:

Text
GET /<logs-{now/d}>/_search          (as written)
GET /%3Clogs-%7Bnow%2Fd%7D%3E/_search   (encoded: logs-2026.11.10 today)
GET /<logs-{now/d-1d}>/_search       (yesterday's index)

Query-string options available on almost every request:

Parameter Effect
pretty Indent the JSON response (debugging only)
human Show sizes and times in readable units (1.2mb, 3s) as well as raw numbers
error_trace Add the Java stack trace to an error response
filter_path Keep only the named parts of the response, e.g. filter_path=hits.hits._id
timeout, master_timeout How long to wait for the shards or for the master node
flat_settings Show settings as index.number_of_shards instead of nested objects
format, v, h, s On _cat APIs: output format, headers, columns, sort

Units. Durations are written 500ms, 30s, 5m, 1d; sizes 10kb, 5gb; distances 12km, 5mi. Booleans are true and false.

Bodies and content types. JSON bodies need Content-Type: application/json. The bulk API uses newline-delimited JSON with application/x-ndjson. GET with a body is allowed for search, and clients that cannot send one may use POST. A small search can also go in the URL with the Lucene-syntax parameter, as in GET /products/_search?q=name:apple; it is handy for quick checks but too limited for real applications.

Status codes. 200 for success, 201 for created, 400 for a malformed request, 401/403 for authentication and authorization, 404 for a missing document or index, 409 for a version conflict, 429 when the cluster is rejecting work because it is overloaded.

Access control by URL. Because every operation is a method plus a path, security roles map onto them: a role grants privileges such as read or write on index name patterns, and the cluster refuses a request whose path targets something the user's role does not allow. See Security and Operations.

Cluster health

The first request to learn after "hello" is health:

JSON
GET /_cluster/health

A typical answer on a healthy single node with no indexes:

JSON
{
  "cluster_name": "docker-cluster",
  "status": "green",
  "number_of_nodes": 1,
  "active_primary_shards": 0,
  "active_shards": 0,
  "unassigned_shards": 0
}

The status is one of three colors:

  • green: every primary and replica shard is allocated;
  • yellow: all primaries are allocated but some replicas are not;
  • red: at least one primary shard is missing, so some data cannot be searched.

On a single node, an index with the default of one replica turns yellow. A replica is never placed on the same node as its primary (a copy on the same machine would not help if it failed), so the replica waits for a second node. In a development container, yellow is normal. Shards are explained in Shards, Replicas and Clusters.

Version notes for 9.x

This tutorial targets the 9.x line. A few facts help when you read older material:

  • Elasticsearch 8 introduced default security and removed mapping types: documents live in an index, and the endpoint is _doc.
  • Elasticsearch 9 builds on a newer Lucene (10) and continues the API you see here; the basics in this tutorial work the same on recent 8.x versions.
  • Very old articles use /index/type/id paths and unsecured http:// examples. Those no longer apply.
  • Check the release notes before upgrading, and always upgrade one major version at a time through the last minor of the previous major.

A mock of the REST API

The stand-in below implements a handful of endpoints in memory: GET /, GET /_cluster/health, creating an index, indexing and fetching a document, and a match_all search. It prints answers with Elasticsearch-like field names. Real behavior (analysis, shards, scoring) is not modeled here.

JS A mock REST API: method, path, body

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Read the output from top to bottom. Creating the index returns acknowledged. The first PUT of document 1 reports created with status 201; the second PUT to the same id reports updated, because a PUT with an id replaces the document. A missing document gives 404 with found: false, and a missing index gives an index_not_found_exception. These status codes and result words match what the real API uses. The mock's health turns yellow once an index exists, copying what a real single node does with the default replica setting; the real reason is shard allocation, not an index count.

Reading errors

Real errors are JSON as well. They have an error object with a type and a reason, and the HTTP status tells you the class of problem: 400 for a bad request, 401 for missing credentials, 404 for a missing index or document, 429 when the cluster is overloaded. Read the reason; it is usually specific.

The second stand-in is a tiny pretty-printer that turns such an answer into one readable line. It is the habit worth building: always look at the status and the reason first.

JS Reading status codes and errors

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does http://localhost:9200 fail on a fresh Elasticsearch 9 node?

    Recent versions enable TLS and authentication automatically. Use https:// with the elastic user's password or an API key.
  2. 2. What are the three parts of almost every example request in this tutorial?

    Dev Tools format is a method such as GET or PUT, a path such as /notes/_doc/1, and an optional JSON body.
  3. 3. A single-node development cluster shows yellow after you create an index with default settings. Why?

    Yellow means all primaries are allocated but some replicas are not. With one node there is nowhere to put the replica.
  4. 4. What does PUT /notes/_doc/1 do when document 1 already exists?

    Indexing with an explicit id overwrites the existing document and the response says result: updated.

Summary

  • Elasticsearch is controlled by HTTP requests with JSON; curl, Kibana Dev Tools and client libraries all send the same calls.
  • A Docker container with discovery.type=single-node is the quickest development setup.
  • Security (HTTPS, passwords, API keys) is on by default since version 8; keep it on.
  • GET /_cluster/health returns green, yellow or red; yellow on one node is normal for indexes with replicas.
  • Status codes and JSON error type and reason fields tell you what went wrong.
  • The JavaScript mock here only models request and response shapes, not the real engine.

Next: Documents, Indexes and CRUD.