2021-05-05 13:09:47 -04:00
---
layout: default
title: Docker
2021-05-06 22:20:19 -04:00
parent: Install OpenSearch
grand_parent: OpenSearch
2021-05-05 13:09:47 -04:00
nav_order: 1
---
# Docker image
You can pull the OpenSearch Docker image just like any other image:
```bash
2021-05-10 13:01:54 -04:00
docker pull opensearchproject/opensearch:{{site.opensearch_version}}
docker pull opensearchproject/opensearch-dashboards:{{site.opensearch_version}}
2021-05-05 13:09:47 -04:00
```
2021-05-06 15:39:58 -04:00
To check available versions, see [Docker Hub ](https://hub.docker.com/u/opensearch ).
2021-05-05 13:09:47 -04:00
OpenSearch images use `centos:7` as the base image. If you run Docker locally, we recommend allowing Docker to use at least 4 GB of RAM in **Preferences** > **Resources** .
---
#### Table of contents
1. TOC
{:toc}
---
## Run the image
To run the image for local development:
```bash
2021-05-10 13:01:54 -04:00
docker run -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" opensearchproject/opensearch:{{site.opensearch_version}}
2021-05-05 13:09:47 -04:00
```
Then send requests to the server to verify that OpenSearch is up and running:
```bash
curl -XGET https://localhost:9200 -u 'admin:admin' --insecure
curl -XGET https://localhost:9200/_cat/nodes?v -u 'admin:admin' --insecure
curl -XGET https://localhost:9200/_cat/plugins?v -u 'admin:admin' --insecure
```
To find the container ID:
```bash
docker ps
```
Then you can stop the container using:
```bash
docker stop < container-id >
```
## Start a cluster
To deploy multiple nodes and simulate a more realistic deployment, create a [docker-compose.yml ](https://docs.docker.com/compose/compose-file/ ) file appropriate for your environment and run:
```bash
docker-compose up
```
To stop the cluster, run:
```bash
docker-compose down
```
To stop the cluster and delete all data volumes, run:
```bash
docker-compose down -v
```
#### Sample Docker Compose file
This sample file starts two data nodes and a container for OpenSearch Dashboards.
```yml
version: '3'
services:
opensearch-node1:
2021-05-10 13:01:54 -04:00
image: opensearchproject/opensearch:{{site.opensearch_version}}
2021-05-05 13:09:47 -04:00
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
- "ES_JAVA_OPTS=-Xms512m -Xmx512m" # minimum and maximum Java heap size, recommend setting both to 50% of system RAM
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:
2021-05-10 13:01:54 -04:00
image: opensearchproject/opensearch:{{site.opensearch_version}}
2021-05-05 13:09:47 -04:00
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
- "ES_JAVA_OPTS=-Xms512m -Xmx512m"
ulimits:
memlock:
soft: -1
hard: -1
nofile:
soft: 65536
hard: 65536
volumes:
- opensearch-data2:/usr/share/opensearch/data
networks:
- opensearch-net
opensearch-dashboards:
2021-05-10 13:01:54 -04:00
image: opensearchproject/opensearch-dashboards:{{site.opensearch_version}}
2021-05-05 13:09:47 -04:00
container_name: opensearch-dashboards
ports:
- 5601:5601
expose:
- "5601"
environment:
OPENSEARCH_HOSTS: https://opensearch-node1:9200
networks:
- opensearch-net
volumes:
opensearch-data1:
opensearch-data2:
networks:
opensearch-net:
```
If you override `opensearch_dashboards.yml` settings using environment variables, as seen above, use all uppercase letters and periods in place of underscores (e.g. for `opensearch.url` , specify `OPENSEARCH_URL` ).
{: .note}
## Configure OpenSearch
You can pass a custom `opensearch.yml` file to the Docker container using the [`-v` flag ](https://docs.docker.com/engine/reference/commandline/run/#mount-volume--v---read-only ) for `docker run` :
```bash
docker run \
-p 9200:9200 -p 9600:9600 \
-e "discovery.type=single-node" \
-v /< full-path-to > /custom-opensearch.yml:/usr/share/opensearch/config/opensearch.yml \
2021-05-10 13:01:54 -04:00
opensearchproject/opensearch:{{site.opensearch_version}}
2021-05-05 13:09:47 -04:00
```
You can perform the same operation in `docker-compose.yml` using a relative path:
```yml
services:
opensearch-node1:
volumes:
- opensearch-data1:/usr/share/opensearch/data
- ./custom-opensearch.yml:/usr/share/opensearch/config/opensearch.yml
opensearch-node2:
volumes:
- opensearch-data2:/usr/share/opensearch/data
- ./custom-opensearch.yml:/usr/share/opensearch/config/opensearch.yml
opensearch-dashboards
volumes:
- ./custom-opensearch_dashboards.yml:/usr/share/opensearch-dashboards/config/opensearch_dashboards.yml
```
2021-05-06 22:20:19 -04:00
You can use this same method to [pass your own certificates ](../docker-security/ ) to the containers for use with the [Security ](../../../security/configuration/ ) plugin.
2021-05-05 13:09:47 -04:00
### (Optional) Set up Performance Analyzer
1. Enable the Performance Analyzer plugin:
```bash
curl -XPOST localhost:9200/_opensearch/_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:
```bash
curl -XPOST https://localhost:9200/_opensearch/_performanceanalyzer/cluster/config -H 'Content-Type: application/json' -d '{"enabled": true}' -u 'admin:admin' -k
```
1. Enable the Root Cause Analyzer (RCA) framework
```bash
curl -XPOST localhost:9200/_opensearch/_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
```bash
curl -XPOST https://localhost:9200/_opensearch/_performanceanalyzer/rca/cluster/config -H 'Content-Type: application/json' -d '{"enabled": true}' -u 'admin:admin' -k
```
1. 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:
```bash
docker ps # Look up the container id
docker exec -it < container-id > /bin/bash
# Inside container
cd plugins/opensearch_performance_analyzer/pa_config/
vi performance-analyzer.properties
```
Uncomment the line `#webservice-bind-host` and set it to `0.0.0.0` :
```
# ======================== OpenSearch performance analyzer plugin config =========================
# NOTE: this is an example for Linux. Please modify the config accordingly if you are using it under other OS.
# WebService bind host; default to all interfaces
webservice-bind-host = 0.0.0.0
# Metrics data location
metrics-location = /dev/shm/performanceanalyzer/
# Metrics deletion interval (minutes) for metrics data.
# Interval should be between 1 to 60.
metrics-deletion-interval = 1
# If set to true, the system cleans up the files behind it. So at any point, we should expect only 2
# metrics-db-file-prefix-path files. If set to false, no files are cleaned up. This can be useful, if you are archiving
# the files and wouldn't like for them to be cleaned up.
cleanup-metrics-db-files = true
# WebService exposed by App's port
webservice-listener-port = 9600
# Metric DB File Prefix Path location
metrics-db-file-prefix-path = /tmp/metricsdb_
https-enabled = false
#Setup the correct path for certificates
certificate-file-path = specify_path
private-key-file-path = specify_path
# Plugin Stats Metadata file name, expected to be in the same location
plugin-stats-metadata = plugin-stats-metadata
# Agent Stats Metadata file name, expected to be in the same location
agent-stats-metadata = agent-stats-metadata
```
1. Then restart the Performance Analyzer agent:
```bash
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:
```bash
docker exec -it < container-id > /bin/bash
```
## Customize the Docker image
To run the image with a custom plugin, first create a [`Dockerfile` ](https://docs.docker.com/engine/reference/builder/ ):
```
2021-05-10 13:01:54 -04:00
FROM opensearchproject/opensearch:{{site.opensearch_version}}
2021-05-05 13:09:47 -04:00
RUN /usr/share/opensearch/bin/opensearch-plugin install --batch < plugin-name-or-url >
```
Then run the following commands:
```bash
docker build --tag=opensearch-custom-plugin .
docker run -p 9200:9200 -p 9600:9600 -v /usr/share/opensearch/data opensearch-custom-plugin
```
2021-05-06 22:20:19 -04:00
You can also use a `Dockerfile` to pass your own certificates for use with the [Security ](../../../security/ ) plugin, similar to the `-v` argument in [Configure OpenSearch ](#configure-opensearch ):
2021-05-05 13:09:47 -04:00
```
2021-05-10 13:01:54 -04:00
FROM opensearchproject/opensearch:{{site.opensearch_version}}
2021-05-05 13:09:47 -04:00
COPY --chown=opensearch:opensearch opensearch.yml /usr/share/opensearch/config/
COPY --chown=opensearch:opensearch my-key-file.pem /usr/share/opensearch/config/
COPY --chown=opensearch:opensearch my-certificate-chain.pem /usr/share/opensearch/config/
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:
```
2021-05-10 13:01:54 -04:00
FROM opensearchproject/opensearch:{{site.opensearch_version}}
2021-05-05 13:09:47 -04:00
RUN /usr/share/opensearch/bin/opensearch-plugin remove opensearch_security
COPY --chown=opensearch:opensearch opensearch.yml /usr/share/opensearch/config/
```
In this case, `opensearch.yml` is a "vanilla" version of the file with no OpenSearch entries. It might look like this:
```yml
cluster.name: "docker-cluster"
network.host: 0.0.0.0
```