Installing OpenSearch

1. With Docker Compose #

A node and its console.

The stack #

Since version 2.12, a strong admin password is mandatory: without it, or if it is too weak, OpenSearch stops at startup. Put it in a .env file, out of Git.

OPENSEARCH_INITIAL_ADMIN_PASSWORD=Str0ng!Passw0rd-2026

services:
  opensearch:
    image: opensearchproject/opensearch:3
    environment:
      discovery.type: single-node
      OPENSEARCH_INITIAL_ADMIN_PASSWORD: ${OPENSEARCH_INITIAL_ADMIN_PASSWORD}
      OPENSEARCH_JAVA_OPTS: -Xms1g -Xmx1g
      path.repo: /usr/share/opensearch/data/snapshots
    ports:
      - "9200:9200"
    volumes:
      - os-data:/usr/share/opensearch/data

  dashboards:
    image: opensearchproject/opensearch-dashboards:3
    environment:
      OPENSEARCH_HOSTS: '["https://opensearch:9200"]'
    ports:
      - "5601:5601"
    depends_on: [opensearch]

volumes:
  os-data:

sudo sysctl -w vm.max_map_count=262144
docker compose up -d
curl -sk -u 'admin:Str0ng!Passw0rd-2026' -H 'Content-Type: application/json' https://localhost:9200/_cat/health?v

The console is at http://localhost:5601 (user admin).

Host settings #

Does the container stop immediately? Check vm.max_map_count on the Linux host: the expected value is 262144. Make it permanent in /etc/sysctl.conf.

2. With the archive #

Without a container.

Installing on a server #

tar -xf opensearch-3.9.0-linux-x64.tar.gz && cd opensearch-3.9.0
echo 'discovery.type: single-node' >> config/opensearch.yml
export OPENSEARCH_INITIAL_ADMIN_PASSWORD='Str0ng!Passw0rd-2026'
./opensearch-tar-install.sh

The script installs demo certificates and starts the node over HTTPS, hence the -k option of curl. For real production, replace these certificates.

Multiple garbage collectors selected message? We hit it on 3.9 with the archive: it came from an OPENSEARCH_JAVA_OPTS exported in the environment. Set memory in config/jvm.options instead.

3. Sizing memory #

The most important setting.

The JVM heap #

Set -Xms and -Xmx to the same value, about half of the machine's memory, and no more than 32 GB. The rest serves the system cache, heavily used by Lucene.

-Xms4g
-Xmx4g