[Tutorial] Running OpenSearch Locally in Docker

1.7K

This tutorial will demonstrate how to run an AWS OpenSearch Docker image in a container for both single and multi-data node configurations. OpenSearch Docker compose files will be used to orchestrate Docker OpenSearch data node instances alongside OpenSearch Dashboards to help query your data.

Read this article before? Jump to the Sloth Summary for docker-compose files to download!

AWS Managed OpenSearch Docker Image

When exploring Amazon Web Service’s managed OpenSearch Service for the first time, you might wonder how you develop against the product locally. It’s a good question because running hosted infrastructure on any web platform will incur a cost.

The good news is that through the magic of Docker we’re able to run a cluster locally for free! You’ll be able to explore this wonderful new technology at your own pace without worrying about accruing costs in the background.

Unfortunately, at the time of writing, we can download no Windows binaries to run OpenSearch. This means that the Docker solution is our only option. If you previously ran ElasticSearch on Windows this will be a slight change to your development workflow, however, getting started is simple.

Docker OpenSearch Pre-Requisite

If you haven’t worked with Docker before, don’t stress. While this is not a Docker tutorial, the steps in the article are everything you need to get your cluster up and running.

Docker is a huge topic and I’ve published an entire article on it. However, a wise Code Sloth doesn’t get bogged down in unnecessary detail, so follow this link to jump to the section on installing Docker Desktop and come straight back. 

Running an OpenSearch Docker Compose File for Multi Data Node Cluster

OpenSearch as a managed service is great because it abstracts away a lot of the complexity of low-level cluster configuration. This becomes apparent very quickly when we take a look at the sample Docker compose file for OpenSearch. Feel free to follow along with the steps below, or skip to the Sloth Summary for a complete Dockerfile and PowerShell script to run it.

In this instance, to make the OpenSearch Docker file:

1. Create a new file on your computer called docker-compose.yml
2. Copy the sample from the OpenSearch website into the file and save it

To run the Docker file:

1. Open a PowerShell terminal in the folder that you saved the file to
2. Type  docker-compose up and hit enter

By default, Docker will look for a file in the current directory named docker-compose.yml and execute it.

To view the running compose file, right click the Docker icon in the system tray and select Dashboard.

Sounds too easy, right?! 

Indeed it is. There are a couple of hurdles to jump before things will run smoothly.

Docker OpenSearch Errors

OpenSearch Docker Image Virtual Memory is Too Low

Running the default Docker Compose file from OpenSearch will surface our first error.

<code>opensearch-node1 | [1]: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]</code>

Luckily this issue is discussed in the elastic.co documentation. We need to set the vm.max_map_count in WSL to a larger value. However, the recommended script doesn’t persist the changed setting after you reboot your machine.

This isn’t great for our OpenSearch engineering workflow, as each time we wanted to work with a cluster we’d need to:

1. Run WSL command 1
2. Run WSL command 2
3. Run Docker Compose command

Let’s Code Sloth-ify this down to a much more repeatable process. Create a new file called RunOpenSearch.ps1 in the same folder as your Docker Compose file and paste this sample into it. 

wsl -d docker-desktop sh -c "sysctl -w vm.max_map_count=262144"
docker-compose up

This script:

1. Joins the individual steps of the elastic.co recommendation into a single step (credit to this StackOverflow answer for describing how to add arguments onto the wsl command).
2. The second tells Docker to spin up the docker-compose.yml file in the current directory.

Each time you need to run your OpenSearch cluster can can now right click the file and select Run with PowerShell. Alternatively you can right click within the folder, select Open Terminal , type RunOpenSearch.ps1 and hit enter.

Either way, you’ll never have to worry about the memory issue again!

WSL Command Not Setting Increased Memory

If you find that the error persists after running the command above, try running wsl --update. After upgrading from Windows 10 to Windows 11, the WSL command started failing to run, and updating wsl fixed the issue.

OpenSearch Docker Compose SSL Connectivity Issues

After running your cluster, you’ll progress further than before. However, the next issue will pop up when you try to connect to it.

opensearch-node1 | [2022-06-25T04:37:37,482][ERROR][o.o.s.s.h.n.SecuritySSLNettyHttpServerTransport] [opensearch-node1] Exception during establishing a SSL connection: io.netty.handler.ssl.NotSslRecordException: not an SSL/TLS record:

This issue arises because SSL is enabled by default on the OpenSearch cluster. This setting can be explicitly disabled by setting an environment variable plugins.security.disabled=true in each of the node containers in the docker compose file.

version: '3'
services:
  opensearch-node1:  
      - plugins.security.disabled=true # additional configuration to disable security by default for local development
  opensearch-node2:
      - plugins.security.disabled=true # additional configuration to disable security by default for local development

A completely updated compose file can be found in the Sloth Summary of this post.

Additional SSL Connectivity Issues From OpenSearch Docker Compose

Now you’re able to run the two nodes and connect to them with an external tool such as Multi ElasticSearch Head Chrome Extension. However, if you try to use OpenSearch Dashboards by navigating to http://localhost:5601 you’ll hit another bump.

opensearch-dashboards | {"type":"log","@timestamp":"2022-06-30T04:01:32Z","tags":["error","opensearch","data"],"pid":1,"message":"[ConnectionError]: write EPROTO 139836736485248:error:1408F10B:SSL routines:ssl3_get_record:wrong version number:../deps/openssl/openssl/ssl/record/ssl3_record.c:332:\n"}

This is the same SSL issue that we encountered for our nodes.

Adjusting the OpenSearch Dashboard configuration section to take a list of environment variables and specifying the DISABLE_SECURITY_DASHBOARDS_PLUGIN variable will fix this.

opensearch-dashboards:
    image: opensearchproject/opensearch-dashboards:2.0.1
    container_name: opensearch-dashboards
    ports:
      - 5601:5601
    expose:
      - "5601"
    environment:
      - 'OPENSEARCH_HOSTS=["http://opensearch-node1:9200","http://opensearch-node2:9200"]'
      - "DISABLE_SECURITY_DASHBOARDS_PLUGIN=true" # disables security dashboards plugin in OpenSearch Dashboards

We will touch on OpenSearch Dashboards (previously called Kibana) in a future tutorial article. But for now you can think of it as another tool that lets you write queries against your cluster.

Now you’re up and running with OpenSearch!

Sloth Summary

In sloth, to get OpenSearch running locally on Windows:

1. Make a docker compose file that has security disabled for each node and OpenSearch Dashboards
2. Define a PowerShell script to:
   1. Increase WSL memory limits
   2. Run docker compose up

Happy open searching!

Docker OpenSearch Script

The following script can be used to run your OpenSearch Docker compose file of choice below. Copy this and save it into a .ps1 file to run from PowerShell.

wsl -d docker-desktop sh -c "sysctl -w vm.max_map_count=262144"
docker-compose up

Multi Data Node OpenSearch Docker Compose File with OpenSearch Dashboards

Copy the following into a file called docker-compose.yml within the same directory as the above PowerShell script to run 3 containers:

• OpenSearch Data Node 1
• OpenSearch Data Node 2
• OpenSearch Dashboards

version: '3'
services:
  opensearch-node1:
    image: opensearchproject/opensearch:2.0.1
    container_name: opensearch-node1
    environment:
      - cluster.name=opensearch-cluster
      - node.name=opensearch-node1
      - discovery.seed_hosts=opensearch-node1,opensearch-node2
      - cluster.initial_master_nodes=opensearch-node1,opensearch-node2
      - bootstrap.memory_lock=true # along with the memlock settings below, disables swapping
      - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" # minimum and maximum Java heap size, recommend setting both to 50% of system RAM
      - plugins.security.disabled=true # additional configuration to disable security by default for local development
    ulimits:
      memlock:
        soft: -1
        hard: -1
      nofile:
        soft: 65536 # maximum number of open files for the OpenSearch user, set to at least 65536 on modern systems
        hard: 65536
    volumes:
      - opensearch-data1:/usr/share/opensearch/data
    ports:
      - 9200:9200
      - 9600:9600 # required for Performance Analyzer
    networks:
      - opensearch-net
  opensearch-node2:
    image: opensearchproject/opensearch:2.0.1
    container_name: opensearch-node2
    environment:
      - cluster.name=opensearch-cluster
      - node.name=opensearch-node2
      - discovery.seed_hosts=opensearch-node1,opensearch-node2
      - cluster.initial_master_nodes=opensearch-node1,opensearch-node2
      - bootstrap.memory_lock=true
      - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m"
      - plugins.security.disabled=true # additional configuration to disable security by default for local development
    ulimits:
      memlock:
        soft: -1
        hard: -1
      nofile:
        soft: 65536
        hard: 65536
    volumes:
      - opensearch-data2:/usr/share/opensearch/data
    networks:
      - opensearch-net
  opensearch-dashboards:
    image: opensearchproject/opensearch-dashboards:2.0.1
    container_name: opensearch-dashboards
    ports:
      - 5601:5601
    expose:
      - "5601"
    environment:
      - 'OPENSEARCH_HOSTS=["http://opensearch-node1:9200","http://opensearch-node2:9200"]'
      - "DISABLE_SECURITY_DASHBOARDS_PLUGIN=true" # disables security dashboards plugin in OpenSearch Dashboards
    networks:
      - opensearch-net

volumes:
  opensearch-data1:
  opensearch-data2:

networks:
  opensearch-net:

Single Data Node OpenSearch Docker Compose File with OpenSearch Dashboards

Copy the following into a file called docker-compose.yml within the same directory as the above PowerShell script to run 2 containers:

• OpenSearch Data Node 1
• OpenSearch Dashboards

version: '3'
services:
  opensearch-node1:
    image: opensearchproject/opensearch:2.0.1
    container_name: opensearch-node1
    environment:
      - cluster.name=opensearch-cluster
      - node.name=opensearch-node1
      - discovery.seed_hosts=opensearch-node1
      - cluster.initial_master_nodes=opensearch-node1
      - bootstrap.memory_lock=true # along with the memlock settings below, disables swapping
      - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" # minimum and maximum Java heap size, recommend setting both to 50% of system RAM
      - plugins.security.disabled=true # additional configuration to disable security by default for local development
    ulimits:
      memlock:
        soft: -1
        hard: -1
      nofile:
        soft: 65536 # maximum number of open files for the OpenSearch user, set to at least 65536 on modern systems
        hard: 65536
    volumes:
      - opensearch-data1:/usr/share/opensearch/data
    ports:
      - 9200:9200
      - 9600:9600 # required for Performance Analyzer
    networks:
      - opensearch-net
  
  opensearch-dashboards:
    image: opensearchproject/opensearch-dashboards:2.0.1
    container_name: opensearch-dashboards
    ports:
      - 5601:5601
    expose:
      - "5601"
    environment:
      - 'OPENSEARCH_HOSTS=["http://opensearch-node1:9200"]'
      - "DISABLE_SECURITY_DASHBOARDS_PLUGIN=true" # disables security dashboards plugin in OpenSearch Dashboards
    networks:
      - opensearch-net

volumes:
  opensearch-data1:

networks:
  opensearch-net: