How to Install Elasticsearch 8 on Debian

Full-text search, log analytics, and metrics dashboards are easier to run on Debian when the official Elasticsearch 8.x packages handle secure defaults from the start.

Since the project is source-available under the Elastic License 2.0 and SSPL, the steps below use the supported Elastic repository and keep the default security configuration. By the end, you will have Elasticsearch running under systemd with TLS, an elastic superuser password, and a verified HTTPS API response.

Choose Your Elasticsearch 8 Installation Method

In practice, the Elastic 8.x repository can be enabled with Debian’s extrepo tool or configured manually. The table below highlights the trade-offs so you can pick the best fit.

Method	Channel	Version	Updates	Best For
extrepo (Recommended)	Elastic Debian package guide	8.x (current stable)	Automatic via apt upgrade	Most users who want managed repo setup
Manual APT repository	Elastic Debian package guide	8.x (current stable)	Automatic via apt upgrade	Scripted deployments or explicit control

In most cases, extrepo is recommended because it manages the GPG key and repository file automatically. Use the manual method if you need explicit control over the repo file for automation or compliance.

Method 1: Enable the Elastic 8 Repository with extrepo (Recommended)

Install extrepo

First, refresh your package index and install extrepo:

sudo apt update
sudo apt install extrepo -y

Enable the Elastic 8 repository

Next, enable the Elastic 8.x repository entry managed by extrepo:

sudo extrepo enable elastic_8

Refresh APT and verify the repository

Afterward, update the package cache and confirm that the elasticsearch package is available:

sudo apt update

apt-cache policy elasticsearch

Expected output:

elasticsearch:
  Installed: (none)
  Candidate: 8.19.9
  Version table:
     8.19.9 500
        500 https://artifacts.elastic.co/packages/8.x/apt stable/main amd64 Packages

As Elastic publishes updates, the version will change. The repository suite remains stable across Debian 11, 12, and 13.

Method 2: Add the Elastic 8 Repository Manually

Install prerequisite packages

Before adding the repository manually, install the tools needed to fetch the signing key and create the repository file:

sudo apt update
sudo apt install ca-certificates curl gnupg -y

Import the Elastic signing key

Then download and install the Elastic signing key for APT verification:

curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearmor -o /usr/share/keyrings/elasticsearch.gpg

Create the DEB822 sources file

After that, define the Elastic 8.x repository using the DEB822 format:

cat <<EOF | sudo tee /etc/apt/sources.list.d/elasticsearch.sources
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Architectures: $(dpkg --print-architecture)
Signed-By: /usr/share/keyrings/elasticsearch.gpg
EOF

This guide uses DEB822 .sources files for third-party repositories to keep APT configuration consistent and readable. For format details, see the DEB822 format reference.

Update APT and verify the package

Now refresh the package cache and confirm the repository is active:

sudo apt update

apt-cache policy elasticsearch

Expected output:

elasticsearch:
  Installed: (none)
  Candidate: 8.19.9
  Version table:
     8.19.9 500
        500 https://artifacts.elastic.co/packages/8.x/apt stable/main amd64 Packages

If you see duplicate repository warnings, remove any extra Elastic .sources or legacy .list files under /etc/apt/sources.list.d/ and run sudo apt update again.

Install Elasticsearch 8

Once the repository is enabled using either method, install Elasticsearch:

sudo apt install elasticsearch -y

Also, the official package bundles a supported JDK under /usr/share/elasticsearch/jdk, so you do not need to install Java separately.

During installation, Elasticsearch prints security auto-configuration details like the generated elastic user password:

--------------------------- Security autoconfiguration information ------------------------------

Authentication and authorization are enabled.
TLS for the transport and HTTP layers is enabled and configured.

The generated password for the elastic built-in superuser is : YOUR_GENERATED_PASSWORD

If this node should join an existing cluster, you can reconfigure this with
'/usr/share/elasticsearch/bin/elasticsearch-reconfigure-node --enrollment-token <token-here>'
after creating an enrollment token on your existing cluster.

You can complete the following actions at any time:

Reset the password of the elastic built-in superuser with 
'/usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic'.

Generate an enrollment token for Kibana instances with 
 '/usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s kibana'.

Generate an enrollment token for Elasticsearch nodes with 
'/usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s node'.

-------------------------------------------------------------------------------------------------

For safety, save the generated password immediately. It is shown once during installation. If you lose it, reset it with the command shown later in this guide.

Enable and Start the Elasticsearch Service

By default, Elasticsearch does not start automatically after installation. Reload systemd, then enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable elasticsearch --now

For reference, service logs are written to /var/log/elasticsearch/, and the main configuration file is /etc/elasticsearch/elasticsearch.yml.

Verify Elasticsearch Installation

Check the installed package version

Next, confirm the package is installed and note the version:

dpkg -s elasticsearch | grep -E '^Status|^Version'

Status: install ok installed
Version: 8.19.9

Reset the elastic password if needed

If you did not save the password shown during installation, reset it with the built-in tool:

Because this command connects to the local node, make sure Elasticsearch is running before you use it.

sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic -b

Password for the [elastic] user successfully reset.
New value: hbvXNMK_m+EcXd4IrG*_

Your password will be different each time you reset it. Store it securely before proceeding.

Test the HTTPS API

If curl is not installed, add it with sudo apt install curl -y; otherwise, continue below. The curl command guide explains common flags and authentication patterns.

Then use the auto-generated CA certificate to connect securely:

curl -s --cacert /etc/elasticsearch/certs/http_ca.crt -u elastic:YOUR_PASSWORD https://localhost:9200

{
  "name" : "5ca2df161c1f",
  "cluster_name" : "elasticsearch",
  "cluster_uuid" : "PVQPLIHURqm2c2c1cmZhIg",
  "version" : {
    "number" : "8.19.9",
    "build_flavor" : "default",
    "build_type" : "deb",
    "build_hash" : "f60dd5fdef48c4b6cf97721154cd49b3b4794fb0",
    "build_date" : "2025-12-16T22:07:42.115850075Z",
    "build_snapshot" : false,
    "lucene_version" : "9.12.2",
    "minimum_wire_compatibility_version" : "7.17.0",
    "minimum_index_compatibility_version" : "7.0.0"
  },
  "tagline" : "You Know, for Search"
}

In response, your output will show your node name, cluster UUID, and the current Elastic version.

Check cluster health

To confirm overall status, query the health endpoint for a quick status summary:

curl -s --cacert /etc/elasticsearch/certs/http_ca.crt -u elastic:YOUR_PASSWORD https://localhost:9200/_cluster/health?pretty

{
  "cluster_name" : "elasticsearch",
  "status" : "green",
  "timed_out" : false,
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "active_primary_shards" : 3,
  "active_shards" : 3,
  "relocating_shards" : 0,
  "initializing_shards" : 0,
  "unassigned_shards" : 0,
  "unassigned_primary_shards" : 0,
  "delayed_unassigned_shards" : 0,
  "number_of_pending_tasks" : 0,
  "number_of_in_flight_fetch" : 0,
  "task_max_waiting_in_queue_millis" : 0,
  "active_shards_percent_as_number" : 100.0
}

However, a single-node cluster can report yellow if replicas cannot be assigned. That is normal unless you expect replicas to be available.

Configure Elasticsearch 8

Although Elasticsearch ships with secure defaults, most deployments still need a few adjustments for naming, memory, and network access.

Review key paths

For reference, these locations are useful for configuration, backups, and troubleshooting:

• Configuration: /etc/elasticsearch/ (includes elasticsearch.yml and jvm.options)
• Custom JVM options: /etc/elasticsearch/jvm.options.d/
• Certificates: /etc/elasticsearch/certs/ (includes http_ca.crt)
• Data: /var/lib/elasticsearch/
• Logs: /var/log/elasticsearch/

Set cluster and node names

To customize names, edit the main configuration file and add the settings you need. Also keep the auto-generated security lines already present in the file.

sudo nano /etc/elasticsearch/elasticsearch.yml

cluster.name: my-application
node.name: node-1

After editing, save the file with Ctrl+O, then exit with Ctrl+X.

Control network exposure

By default, security auto-configuration writes http.host: 0.0.0.0 so HTTPS listens on all interfaces. If you want localhost-only access, set an explicit loopback host:

http.host: 127.0.0.1

Alternatively, to allow remote clients, set network.host to your server IP:

network.host: 192.168.1.10

Security warning: Exposing Elasticsearch without firewall rules or trusted clients can leak sensitive data. Use TLS and authentication (enabled by default) and review the official Elasticsearch security documentation before opening access.

Adjust JVM heap size (optional)

By default, Elasticsearch sizes the JVM heap automatically based on node roles and available memory. However, if you need to override it, create a custom options file that survives upgrades:

sudo nano /etc/elasticsearch/jvm.options.d/custom-heap.options

For example, use the following setting for a 2 GB heap:

-Xms2g
-Xmx2g

As a rule, set Xms and Xmx to the same value and keep the heap at or below 50% of system memory. Elastic also recommends staying below the compressed oops threshold, which is typically 26 GB to 30 GB. See the Elasticsearch JVM settings reference for details.

Set vm.max_map_count for production or non-localhost binds

Before moving Elasticsearch into production or binding to non-localhost interfaces, check the current kernel setting:

sysctl vm.max_map_count

vm.max_map_count = 262144

If your value is below 1048576, raise it and persist the change:

sudo sysctl -w vm.max_map_count=1048576
echo "vm.max_map_count=1048576" | sudo tee -a /etc/sysctl.conf

Elastic documents the 1048576 recommendation in the vm.max_map_count guide. Re-run sysctl vm.max_map_count after changes to confirm the new value.

Apply configuration changes

Finally, restart Elasticsearch after any configuration or JVM changes:

sudo systemctl restart elasticsearch

Configure UFW Firewall Rules (Optional)

If you enable remote access and use UFW, allow the Elasticsearch port explicitly. For detailed firewall setup, see our UFW guide for Debian. Alternatively, if you prefer to terminate TLS and restrict access at a reverse proxy, see Nginx on Debian.

Critical: If you are connected over SSH, allow SSH access before enabling UFW to prevent lockout.

For example, to allow a specific IP to reach Elasticsearch over HTTPS:

sudo ufw allow from 192.168.1.20 to any port 9200 proto tcp

Then replace 192.168.1.20 with the IP that needs access and verify the rule:

sudo ufw status numbered

Status: active

     To                         Action      From
     --                         ------      ----
[ 1] 9200/tcp                   ALLOW IN    192.168.1.20

Troubleshoot Common Elasticsearch Issues

If the API or service does not respond as expected, use the fixes below.

curl shows an SSL certificate error

If you connect without the CA certificate, curl will reject the self-signed chain:

curl: (60) SSL certificate problem: self-signed certificate in certificate chain
More details here: https://curl.se/docs/sslcerts.html

curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the webpage mentioned above.

Instead, fix the request by pointing curl to the Elastic HTTP CA:

curl -s --cacert /etc/elasticsearch/certs/http_ca.crt -u elastic:YOUR_PASSWORD https://localhost:9200

Once it succeeds, a successful response returns the JSON payload shown in the verification section.

curl cannot connect to port 9200

If the service is not running, curl reports a connection failure:

curl: (7) Failed to connect to localhost port 9200 after 0 ms: Could not connect to server

Then start the service and retry the HTTPS API check:

sudo systemctl start elasticsearch

Afterward, re-run the HTTPS API check to confirm it is responding.

401 Unauthorized from the API

If the password is wrong, Elasticsearch responds with a security exception:

{"error":{"root_cause":[{"type":"security_exception","reason":"unable to authenticate user [elastic] for REST request [/]","header":{"WWW-Authenticate":["Basic realm=\"security\", charset=\"UTF-8\"","Bearer realm=\"security\"","ApiKey"]}}],"type":"security_exception","reason":"unable to authenticate user [elastic] for REST request [/]","header":{"WWW-Authenticate":["Basic realm=\"security\", charset=\"UTF-8\"","Bearer realm=\"security\"","ApiKey"]}},"status":401}

Then reset the password and try the API again:

sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic -b

Password for the [elastic] user successfully reset.
New value: hbvXNMK_m+EcXd4IrG*_

Finally, update your curl command with the new password and run the API check again.

Remove Elasticsearch from Debian

Stop and disable the service

Before removing the package, stop the service:

sudo systemctl stop elasticsearch
sudo systemctl disable elasticsearch

Uninstall the package

Next, remove Elasticsearch and any unused dependencies:

sudo apt remove --purge elasticsearch -y
sudo apt autoremove -y

Clean up the repository configuration

If you enabled the repository with extrepo:

sudo extrepo disable elastic_8
sudo rm -f /etc/apt/sources.list.d/extrepo_elastic_8.sources

If you added the repository manually:

sudo rm -f /etc/apt/sources.list.d/elasticsearch.sources
sudo rm -f /usr/share/keyrings/elasticsearch.gpg

Afterward, refresh the package cache:

sudo apt update

Remove data and logs (optional)

Warning: The following commands permanently delete all Elasticsearch indices, cluster state, and logs. This action cannot be undone, so back up any data you need before proceeding.

sudo rm -rf /var/lib/elasticsearch
sudo rm -rf /var/log/elasticsearch

Verify removal

To confirm removal, check that the package is no longer installed:

dpkg -s elasticsearch

dpkg-query: package 'elasticsearch' is not installed and no information is available
Use dpkg --info (= dpkg-deb --info) to examine archive files.

Conclusion

At this point, you have Elasticsearch 8 installed on Debian with secure defaults, verified API access, and a clear path for configuration and maintenance. If you plan to expand to multi-node clusters or integrate Kibana and Logstash, review the official Elasticsearch documentation for cluster design, backups, and production tuning.