Docker image

You can pull the OpenSearch Docker image from either Docker Hub or the public gallery hosted on AWS Elastic Container Registry (ECR).

From Docker Hub:

  1. docker pull opensearchproject/opensearch:latest
  2. docker pull opensearchproject/opensearch-dashboards:latest

From AWS ECR:

  1. docker pull public.ecr.aws/opensearchproject/opensearch:latest
  2. docker pull public.ecr.aws/opensearchproject/opensearch-dashboards:latest

To download a specific version of OpenSearch or OpenSearch Dashboards, modify the image tag (latest) to point to a valid version number. For example, docker pull opensearchproject/opensearch:1.3.0 will download the image corresponding to OpenSearch 1.3.0.

To check available versions, see Docker Hub.

OpenSearch images use amazonlinux:2 as the base image. If you run Docker locally, set Docker to use at least 4 GB of RAM in Preferences > Resources.

Run the image

To run the image for local development:

  1. docker run -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" opensearchproject/opensearch:2.2.1

Then send requests to the server to verify that OpenSearch is up and running:

  1. curl -XGET https://localhost:9200 -u 'admin:admin' --insecure
  2. curl -XGET https://localhost:9200/_cat/nodes?v -u 'admin:admin' --insecure
  3. curl -XGET https://localhost:9200/_cat/plugins?v -u 'admin:admin' --insecure

To find the container ID:

  1. docker ps

Then you can stop the container using:

  1. docker stop <container-id>

Start a cluster

To deploy multiple nodes and simulate a more realistic deployment, create a docker-compose.yml file appropriate for your environment and run:

  1. docker-compose up

To stop the cluster, run:

  1. docker-compose down

To stop the cluster and delete all data volumes, run:

  1. docker-compose down -v

If you’re running your cluster in a production environment, be sure to refer to Important settings when configuring your machine and cluster.

Sample Docker Compose file

This sample file starts two data nodes and a container for OpenSearch Dashboards.

  1. version: '3'
  2. services:
  3.   opensearch-node1:
  4.     image: opensearchproject/opensearch:2.2.1
  5.     container_name: opensearch-node1
  6.     environment:
  7.       - cluster.name=opensearch-cluster
  8.       - node.name=opensearch-node1
  9.       - discovery.seed_hosts=opensearch-node1,opensearch-node2
  10.       - cluster.initial_cluster_manager_nodes=opensearch-node1,opensearch-node2
  11.       - bootstrap.memory_lock=true # along with the memlock settings below, disables swapping
  12.       - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" # minimum and maximum Java heap size, recommend setting both to 50% of system RAM
  13.     ulimits:
  14.       memlock:
  15.         soft: -1
  16.         hard: -1
  17.       nofile:
  18.         soft: 65536 # maximum number of open files for the OpenSearch user, set to at least 65536 on modern systems
  19.         hard: 65536
  20.     volumes:
  21.       - opensearch-data1:/usr/share/opensearch/data
  22.     ports:
  23.       - 9200:9200
  24.       - 9600:9600 # required for Performance Analyzer
  25.     networks:
  26.       - opensearch-net
  27.   opensearch-node2:
  28.     image: opensearchproject/opensearch:2.2.1
  29.     container_name: opensearch-node2
  30.     environment:
  31.       - cluster.name=opensearch-cluster
  32.       - node.name=opensearch-node2
  33.       - discovery.seed_hosts=opensearch-node1,opensearch-node2
  34.       - cluster.initial_cluster_manager_nodes=opensearch-node1,opensearch-node2
  35.       - bootstrap.memory_lock=true
  36.       - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m"
  37.     ulimits:
  38.       memlock:
  39.         soft: -1
  40.         hard: -1
  41.       nofile:
  42.         soft: 65536
  43.         hard: 65536
  44.     volumes:
  45.       - opensearch-data2:/usr/share/opensearch/data
  46.     networks:
  47.       - opensearch-net
  48.   opensearch-dashboards:
  49.     image: opensearchproject/opensearch-dashboards:2.2.1
  50.     container_name: opensearch-dashboards
  51.     ports:
  52.       - 5601:5601
  53.     expose:
  54.       - "5601"
  55.     environment:
  56.       OPENSEARCH_HOSTS: '["https://opensearch-node1:9200","https://opensearch-node2:9200"]' # must be a string with no spaces when specified as an environment variable
  57.     networks:
  58.       - opensearch-net
  60. volumes:
  61.   opensearch-data1:
  62.   opensearch-data2:
  64. networks:
  65.   opensearch-net:

If you override opensearch_dashboards.yml settings using environment variables, as seen above, use all uppercase letters and underscores in place of periods (e.g. for opensearch.hosts, use OPENSEARCH_HOSTS).

Configure OpenSearch

You can pass a custom opensearch.yml file to the Docker container using the -v flag for docker run:

  1. docker run \
  2. -p 9200:9200 -p 9600:9600 \
  3. -e "discovery.type=single-node" \
  4. -v /<full-path-to>/custom-opensearch.yml:/usr/share/opensearch/config/opensearch.yml \
  5. opensearchproject/opensearch:2.2.1

You can perform the same operation in docker-compose.yml using a relative path:

  1. services:
  2.   opensearch-node1:
  3.     volumes:
  4.       - opensearch-data1:/usr/share/opensearch/data
  5.       - ./custom-opensearch.yml:/usr/share/opensearch/config/opensearch.yml
  6.   opensearch-node2:
  7.     volumes:
  8.       - opensearch-data2:/usr/share/opensearch/data
  9.       - ./custom-opensearch.yml:/usr/share/opensearch/config/opensearch.yml
  10.   opensearch-dashboards:
  11.     volumes:
  12.       - ./custom-opensearch_dashboards.yml:/usr/share/opensearch-dashboards/config/opensearch_dashboards.yml

You can also configure docker-compose.yml and opensearch.yml to take your own certificates for use with the Security plugin.

(Optional) Set up Performance Analyzer

  1. Enable the Performance Analyzer plugin:

    1. curl -XPOST localhost:9200/_plugins/_performanceanalyzer/cluster/config -H 'Content-Type: application/json' -d '{"enabled": true}'

    If you receive the curl: (52) Empty reply from server error, you are likely protecting your cluster with the security plugin and you need to provide credentials. Modify the following command to use your username and password:

    1. curl -XPOST https://localhost:9200/_plugins/_performanceanalyzer/cluster/config -H 'Content-Type: application/json' -d '{"enabled": true}' -u 'admin:admin' -k

  2. Enable the Root Cause Analyzer (RCA) framework

    1. curl -XPOST localhost:9200/_plugins/_performanceanalyzer/rca/cluster/config -H 'Content-Type: application/json' -d '{"enabled": true}'

    Similar to step 1, if you run into curl: (52) Empty reply from server, run the command below to enable RCA

    1. curl -XPOST https://localhost:9200/_plugins/_performanceanalyzer/rca/cluster/config -H 'Content-Type: application/json' -d '{"enabled": true}' -u 'admin:admin' -k

  3. By default, Performance Analyzer’s endpoints are not accessible from outside the Docker container.

    To edit this behavior, open a shell session in the container and modify the configuration:

    1. docker ps # Look up the container id
    2. docker exec -it <container-id> /bin/bash
    3. # Inside container
    4. cd config/opensearch-performance-analyzer/
    5. vi performance-analyzer.properties

    Uncomment the line #webservice-bind-host and set it to 0.0.0.0:

    1. # ======================== OpenSearch performance analyzer plugin config =========================
    3. # NOTE: this is an example for Linux. Please modify the config accordingly if you are using it under other OS.
    5. # WebService bind host; default to all interfaces
    6. webservice-bind-host = 0.0.0.0
    8. # Metrics data location
    9. metrics-location = /dev/shm/performanceanalyzer/
    11. # Metrics deletion interval (minutes) for metrics data.
    12. # Interval should be between 1 to 60.
    13. metrics-deletion-interval = 1
    15. # If set to true, the system cleans up the files behind it. So at any point, we should expect only 2
    16. # metrics-db-file-prefix-path files. If set to false, no files are cleaned up. This can be useful, if you are archiving
    17. # the files and wouldn't like for them to be cleaned up.
    18. cleanup-metrics-db-files = true
    20. # WebService exposed by App's port
    21. webservice-listener-port = 9600
    23. # Metric DB File Prefix Path location
    24. metrics-db-file-prefix-path = /tmp/metricsdb_
    26. https-enabled = false
    28. #Setup the correct path for certificates
    29. certificate-file-path = specify_path
    31. private-key-file-path = specify_path
    33. # Plugin Stats Metadata file name, expected to be in the same location
    34. plugin-stats-metadata = plugin-stats-metadata
    36. # Agent Stats Metadata file name, expected to be in the same location
    37. agent-stats-metadata = agent-stats-metadata

  4. Then restart the Performance Analyzer agent:

    1. kill $(ps aux | grep -i 'PerformanceAnalyzerApp' | grep -v grep | awk '{print $2}')

Bash access to containers

To create an interactive Bash session in a container, run docker ps to find the container ID. Then run:

  1. docker exec -it <container-id> /bin/bash

Install, configure or remove plugins

To run the image with a custom plugin, first create a Dockerfile:

  1. FROM opensearchproject/opensearch:2.2.1
  2. RUN /usr/share/opensearch/bin/opensearch-plugin install --batch <plugin-name-or-url>

Then run the following commands:

  1. docker build --tag=opensearch-custom-plugin .
  2. docker run -p 9200:9200 -p 9600:9600 -v /usr/share/opensearch/data opensearch-custom-plugin

You can also use a Dockerfile to pass your own certificates for use with the security plugin, similar to the -v argument in Configure OpenSearch:

  1. FROM opensearchproject/opensearch:2.2.1
  2. COPY --chown=opensearch:opensearch opensearch.yml /usr/share/opensearch/config/
  3. COPY --chown=opensearch:opensearch my-key-file.pem /usr/share/opensearch/config/
  4. COPY --chown=opensearch:opensearch my-certificate-chain.pem /usr/share/opensearch/config/
  5. COPY --chown=opensearch:opensearch my-root-cas.pem /usr/share/opensearch/config/

Alternately, you might want to remove a plugin. This Dockerfile removes the security plugin:

  1. FROM opensearchproject/opensearch:2.2.1
  2. RUN /usr/share/opensearch/bin/opensearch-plugin remove opensearch-security
  3. COPY --chown=opensearch:opensearch opensearch.yml /usr/share/opensearch/config/

In this case, opensearch.yml is a “vanilla” version of the file with no plugin entries. It might look like this:

  1. cluster.name: "docker-cluster"
  2. network.host: 0.0.0.0

Sample Docker Compose file for development

You can use this sample file as a development environment.

This sample file starts one OpenSearch node and a container for OpenSearch Dashboards with the security plugin disabled.

  1. version: '3'
  2. services:
  3.   opensearch-node1:
  4.     image: opensearchproject/opensearch:2.2.1
  5.     container_name: opensearch-node1
  6.     environment:
  7.       - cluster.name=opensearch-cluster
  8.       - node.name=opensearch-node1
  9.       - bootstrap.memory_lock=true # along with the memlock settings below, disables swapping
  10.       - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" # minimum and maximum Java heap size, recommend setting both to 50% of system RAM
  11.       - "DISABLE_INSTALL_DEMO_CONFIG=true" # disables execution of install_demo_configuration.sh bundled with security plugin, which installs demo certificates and security configurations to OpenSearch
  12.       - "DISABLE_SECURITY_PLUGIN=true" # disables security plugin entirely in OpenSearch by setting plugins.security.disabled: true in opensearch.yml
  13.       - "discovery.type=single-node" # disables bootstrap checks that are enabled when network.host is set to a non-loopback address
  14.     ulimits:
  15.       memlock:
  16.         soft: -1
  17.         hard: -1
  18.       nofile:
  19.         soft: 65536 # maximum number of open files for the OpenSearch user, set to at least 65536 on modern systems
  20.         hard: 65536
  21.     volumes:
  22.       - opensearch-data1:/usr/share/opensearch/data
  23.     ports:
  24.       - 9200:9200
  25.       - 9600:9600 # required for Performance Analyzer
  26.     networks:
  27.       - opensearch-net
  29.   opensearch-dashboards:
  30.     image: opensearchproject/opensearch-dashboards:2.2.1
  31.     container_name: opensearch-dashboards
  32.     ports:
  33.       - 5601:5601
  34.     expose:
  35.       - "5601"
  36.     environment:
  37.       - 'OPENSEARCH_HOSTS=["http://opensearch-node1:9200"]'
  38.       - "DISABLE_SECURITY_DASHBOARDS_PLUGIN=true" # disables security dashboards plugin in OpenSearch Dashboards
  39.     networks:
  40.       - opensearch-net
  42. volumes:
  43.   opensearch-data1:
  45. networks:
  46.   opensearch-net:

The environment variable "DISABLE_SECURITY_DASHBOARDS_PLUGIN=true" disables the security dashboards plugin in OpenSearch Dashboards by removing the security dashboards plugin folder, removing all related settings in the opensearch_dashboards.yml file, and setting the opensearch.hosts entry protocol from HTTPS to HTTP. You can’t reverse this step as the security dashboards plugin is removed in the process. To re-enable security for OpenSearch Dashboards, start a new container and set DISABLE_SECURITY_DASHBOARDS_PLUGIN to false or leave it unset.