How to Set Up OpenSearch for Magento 2.4.7 on Ubuntu 22.04/24.04

Version Check Before You Start

Magento pins its search engine per release, and getting this wrong produces indexer errors that look like configuration problems for hours:

This guide targets 2.4.7, but note where it sits: its regular support ends in April 2027, so if you are building fresh, install 2.4.8 and pin OpenSearch 2.19 instead. The steps are identical apart from the version number. Check Adobe's system requirements for your exact patch rather than trusting any guide's table, including this one.

Prerequisites

• Ubuntu 22.04 LTS or 24.04 LTS, root or sudo access
• A LEMP or LAMP stack for Magento, plus Composer
• No separate Java installation. More on this next.

You Do Not Need to Install Java

Most guides open with apt install openjdk-11-jdk. Skip it. The OpenSearch 2.x Debian package bundles its own JDK (Java 17 LTS, in /usr/share/opensearch/jdk). Installing OpenJDK 11 alongside it does nothing useful, and Java 11 is older than what OpenSearch 2.x actually runs on.

The only time you install Java yourself is if you deliberately choose the -no-jdk distribution flavour, which almost nobody does. If you need OpenSearch to use a different JDK, point OPENSEARCH_JAVA_HOME at it rather than installing a system JDK and hoping.

Step 1: Update Packages

sudo apt-get update && sudo apt-get -y upgrade
sudo apt-get -y install lsb-release ca-certificates curl gnupg2

Step 2: Add the OpenSearch Repository

This is the step most guides say to do and then do not show. apt install opensearch fails on a stock Ubuntu box because OpenSearch is not in Ubuntu's repositories.

# Import the signing key
curl -o- https://artifacts.opensearch.org/publickeys/opensearch-release.pgp \
  | sudo gpg --dearmor --batch --yes -o /usr/share/keyrings/opensearch-release-keyring.gpg

# Add the 2.x repo
echo "deb [signed-by=/usr/share/keyrings/opensearch-release-keyring.gpg] \
https://artifacts.opensearch.org/releases/bundle/opensearch/2.x/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/opensearch-2.x.list

sudo apt-get update

Step 3: Install OpenSearch (With the Password It Now Demands)

Since OpenSearch 2.12 the installer refuses to proceed without an initial admin password:

# Pin the version. "Latest" is how you end up on a release Magento does not support.
sudo env OPENSEARCH_INITIAL_ADMIN_PASSWORD='Str0ng!Passw0rd' \
  apt-get -y install opensearch=2.19.0

The password needs at least eight characters with an uppercase letter, a lowercase letter, a number, and a special character. Store it in your password manager now; you will need it the first time you curl the API with security on.

Pinning the version matters. Magento 2.4.8 expects OpenSearch 2.19 specifically, and letting apt install whatever is newest is a reliable way to create an unsupported combination that mostly works until it does not.

Step 4: Single-Node Configuration

Edit /etc/opensearch/opensearch.yml:

cluster.name: magento-cluster
node.name: node-1

# Bind to loopback only. This is the security boundary on a single-host install.
network.host: 127.0.0.1
http.port: 9200

# Single node: do not wait around trying to form a cluster
discovery.type: single-node

discovery.type: single-node is the line that saves an afternoon. Without it, OpenSearch starts, looks for peers that do not exist, never elects a cluster manager, and sits at red health while every Magento reindex fails with a timeout.

About disabling security

You will see plugins.security.disabled: true in most single-node guides. It is a legitimate choice only when OpenSearch is bound to loopback and nothing else shares the host, because with security off, anything that reaches port 9200 has full read and write access with no authentication.

If you go that route, understand that network.host: 127.0.0.1 is the protection, not a firewall rule, and verify it (Step 6). We cover the trade-off and the verification in detail in our guide to disabling OpenSearch security while keeping it private.

For anything production-shaped, leave security enabled and use the admin password from Step 3.

Heap sizing

The default heap is often wrong for a Magento box. Set it in /etc/opensearch/jvm.options:

-Xms2g
-Xmx2g

Two rules that are not negotiable: Xms and Xmx must be identical (a resizing heap causes long pauses), and stay under 32 GB so the JVM keeps compressed object pointers. Half of available RAM is the usual starting point, leaving the rest for the filesystem cache, which OpenSearch leans on heavily.

Step 5: Start It

sudo systemctl daemon-reload
sudo systemctl enable --now opensearch
sudo systemctl status opensearch --no-pager

If it fails to start, the log is the first stop, not a Google search:

sudo journalctl -u opensearch -n 50 --no-pager
sudo tail -50 /var/log/opensearch/magento-cluster.log

The most common first-boot failure is vm.max_map_count being too low:

sudo sysctl -w vm.max_map_count=262144
echo 'vm.max_map_count=262144' | sudo tee /etc/sysctl.d/99-opensearch.conf

Step 6: Verify Before Touching Magento

Prove OpenSearch works on its own first. Debugging Magento against a broken search engine is twice the work.

# What is it ACTUALLY listening on? This is the security check.
sudo ss -tulpn | grep 9200
# Want: 127.0.0.1:9200
# Bad:  0.0.0.0:9200 -> reachable from the network

# With security enabled (default), you need the admin credentials and -k for the demo cert:
curl -k -u admin:'Str0ng!Passw0rd' https://localhost:9200/_cluster/health?pretty

# With security disabled:
curl http://localhost:9200/_cluster/health?pretty

Health should be green on a single node. yellow on a single node usually means an index wants replicas that have nowhere to go, which is normal for a one-node install once Magento creates indices.

Step 7: Point Magento at OpenSearch

For a fresh install, pass it to setup:install:

bin/magento setup:install --base-url=https://your-domain.com/ \
  --db-host=localhost --db-name=magento --db-user=magento_user --db-password='your_password' \
  --admin-firstname=Admin --admin-lastname=User --admin-email=admin@example.com \
  --admin-user=admin --admin-password='Str0ng!Adm1n' --language=en_US \
  --currency=USD --timezone=Europe/Sofia --use-rewrites=1 \
  --search-engine=opensearch \
  --opensearch-host=127.0.0.1 --opensearch-port=9200 \
  --opensearch-index-prefix=magento2 --opensearch-timeout=15

For an existing install:

bin/magento config:set catalog/search/engine opensearch
bin/magento config:set catalog/search/opensearch_server_hostname 127.0.0.1
bin/magento config:set catalog/search/opensearch_server_port 9200
bin/magento config:set catalog/search/opensearch_index_prefix magento2
bin/magento config:set catalog/search/opensearch_server_timeout 15

# If security is ENABLED, Magento needs credentials:
bin/magento config:set catalog/search/opensearch_enable_auth 1
bin/magento config:set catalog/search/opensearch_username admin
bin/magento config:set catalog/search/opensearch_password 'Str0ng!Passw0rd'

bin/magento cache:flush
bin/magento indexer:reindex catalogsearch_fulltext

opensearch_enable_auth must match reality. Security on and auth off gives you connection errors; security off and auth on gives you the same, from the other direction.

Step 8: Verify the Integration, Not Just the Reindex

A reindex that "finishes without errors" and leaves an empty index is a common, confusing outcome. Check the documents actually landed:

curl -k -u admin:'Str0ng!Passw0rd' 'https://localhost:9200/_cat/indices?v'
# Expect a magento2_product_* index with a non-zero docs.count

A docs.count of zero means the reindex found nothing to index (no enabled, visible, in-stock products) or the index prefix does not match. Then search the storefront for a product you know exists. That end-to-end check is the only one that proves the whole chain.

Optional: Multi-Node Cluster

If you need redundancy, spread OpenSearch across nodes. Three corrections to the usual guide before you start.

Use the current setting names

OpenSearch renamed the "master" terminology to "cluster manager" from 1.3 onward. The old names still work in 2.x but log deprecation warnings and are slated for removal:

cluster.name: magento-cluster          # identical on every node
node.name: node-1                      # unique per node
network.host: 10.0.0.11                # this node's PRIVATE ip, never 0.0.0.0

discovery.seed_hosts: ["10.0.0.11", "10.0.0.12", "10.0.0.13"]

# Current name. The old cluster.initial_master_nodes is deprecated.
cluster.initial_cluster_manager_nodes: ["node-1", "node-2", "node-3"]

Use three cluster-manager-eligible nodes, not two. Two cannot form a quorum when one fails, which is the exact scenario you built a cluster for.

network.host: 0.0.0.0 binds to every interface, including public ones. Use the private IP.

Do not open 9200 and 9300 to the world

The standard guide says:

# Do NOT do this. It publishes your search cluster.
sudo ufw allow 9200/tcp
sudo ufw allow 9300/tcp

Port 9300 is the inter-node transport channel. Exposing it to the internet is worse than exposing 9200. Restrict both to the nodes and the Magento hosts:

# On each OpenSearch node: only peers may speak transport
sudo ufw allow from 10.0.0.11 to any port 9300 proto tcp
sudo ufw allow from 10.0.0.12 to any port 9300 proto tcp
sudo ufw allow from 10.0.0.13 to any port 9300 proto tcp

# Only the Magento app server may query the REST API
sudo ufw allow from 10.0.0.20 to any port 9200 proto tcp

Certificates: what securityadmin.sh actually does

Guides commonly show something like securityadmin.sh -cd ... -ca -cert under a heading about generating certificates. That is misleading. securityadmin.sh does not generate certificates. It loads the security configuration (users, roles, mappings) from YAML into the .opendistro_security index. It is a configuration tool, not a certificate authority.

Certificates are a separate job. On a real cluster you need proper node certificates for the transport layer, because a multi-node cluster requires transport TLS: you cannot run one with security disabled. The demo certificates installed by the package are exactly that, demos, and are not for production.

# Apply security CONFIGURATION (not certificate generation)
cd /usr/share/opensearch/plugins/opensearch-security/tools
sudo ./securityadmin.sh \
  -cd /usr/share/opensearch/config/opensearch-security/ \
  -icl -nhnv \
  -cacert /etc/opensearch/root-ca.pem \
  -cert /etc/opensearch/admin.pem \
  -key /etc/opensearch/admin-key.pem

Generating real certificates for each node, distributing them, and setting the correct permissions is genuinely fiddly and is where most self-managed clusters go wrong. If you need a cluster and do not have someone who has done this before, that is a reasonable moment to get help rather than improvise.

Troubleshooting

Service will not start. journalctl -u opensearch -n 50 first. Usually vm.max_map_count, a heap larger than available RAM, or a YAML indentation error.

Health stuck at red on a single node. Missing discovery.type: single-node.

Magento errors connecting. Almost always an opensearch_enable_auth mismatch, or hitting http:// when security is on (it serves HTTPS).

Reindex succeeds, storefront search is empty. Check _cat/indices for a non-zero docs.count, then check products are enabled, visible, and in stock.

Cluster nodes will not join. cluster.name differs, 9300 is firewalled between nodes, or discovery.seed_hosts has the wrong addresses. The log names the reason.

Bottom Line

The install itself is ten minutes once you have the repository right and know the package brings its own Java. The parts that actually cost time are the ones the standard guide skips: pinning the version Magento supports, the admin password the installer now demands, discovery.type on a single node, and verifying with ss and _cat/indices instead of assuming.

If you want the search tier built, secured, and tuned against your real catalogue, or a cluster designed properly rather than assembled from blog posts, that is what our server optimization and Magento work covers.

Sources

• OpenSearch: install on Debian and Ubuntu
• OpenSearch: the end of the default admin password
• OpenSearch: creating a cluster
• OpenSearch: cluster bootstrapping
• OpenSearch: important system settings
• OpenSearch: applying security configuration with securityadmin
• Adobe Commerce system requirements
• Adobe Commerce: configure the search engine