Docker image

To check available versions, see .

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

To run the image for local development:

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

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 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

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).

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. opensearchproject/opensearch:2.0.0

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

  1. services:
  2.   opensearch-node1:
  3.     volumes:
  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 for use with the Security plugin.

  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 exec -it <container-id> /bin/bash
    2. # Inside container
    3. cd config/opensearch-performance-analyzer/
    4. vi performance-analyzer.properties

  4. Then restart the Performance Analyzer agent:

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

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

  1. FROM opensearchproject/opensearch:2.0.0
  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 plugin, similar to the -v argument in Configure OpenSearch:

  1. FROM opensearchproject/opensearch:2.0.0
  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.0.0
  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"

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.

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 to false or leave it unset.