How to Install OpenSearch via Docker on Ubuntu 22.04

OpenSearch is a community-driven project by Amazon and a fork of Elasticsearch and Kibana. It's a fully open-source search engine and analytics suite with rich features and innovative functionality. The OpenSearch project's main component is OpenSearch (a fork of Elasticsearch) and the OpenSearch Dashboards (a fork of Kibana). Both components provide features such as enterprise security, alerting, machine learning, SQL, index state management, and more.

OpenSearch is 100% open-source and licensed under Apache 2.0-licensed. It enables you to easily ingest, secure, search, aggregate, view, and analyze data for a number of use cases such as log analytics, application search, enterprise search, and more.

In this tutorial, you will install and set up OpenSearch - an open-source search engine and analytics suite - and OpenSearch Dashboards - an open-source visualization tool - via Docker on an Ubuntu 22.04 server. You'll deploy an OpenSearch cluster with multiple containers and a single OpenSearch Dashboard via Docker and Docker Compose. You'll also secure your deployment with custom TLS certificates and authentication and authorization enabled.

This guide uses a fresh generic Ubuntu server, so this tutorial includes installing the Docker engine and Docker Compose on an Ubuntu 22.04 system.

Prerequisites

To complete this guide, you must have the following requirements:

  • An Ubuntu 22.04 server with min RAM 4-8GB - This example uses an Ubuntu server with the hostname '' and an IP address ''.
  • A non-root user with sudo/root administrator privileges.

When these requirements are ready, you can now start the OpenSearch installation.

Setting Up System

In this first step, you will prepare your Ubuntu system for the OpenSearch deployment. You'll need to disable SWAP and paging, then you'll increase the max memory map via the '/etc/sysctl.conf' file.

Run the below command to disable the swap on your system. The 'sed' command here will disable swap permanently via the '/etc/fstab' file by adding comment '#' to the beginning of the line swap configuration. The 'swapoff' command will disable swap in the current session.

sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab
sudo swapoff -a

Next, verify the swap status via the below command. If disabled, you should get an output '0' in the swap section.

free -m

Output:

disable swap

Lastly, you'll add the configuration to the '/etc/sysctl.conf' file to increase the max memory maps on your Ubuntu system.

Run the below command to add the parameter 'vm.max_map_count=262144' to the end of the line of the '/etc/sysctl.conf' file. Then, apply the changes via the 'sysctl -p' command.

sudo echo "vm.max_map_count=262144" >> /etc/sysctl.conf
sudo sysctl -p

Now verify the max memory maps by running the below command. If successful, your max memory map should be '262144'.

cat /proc/sys/vm/max_map_count

Output:

setup sysctl

With the swap disabled and the max memory map increased to '262144', you'll next start the installation of the Docker engine and Docker Compose.

Installing Docker CE and Docker Compose

There are multiple ways to deploy and install OpenSearch, you can install OpenSearch in a traditional way on a virtual machine, or install it in the container environment.

If you prefer traditional installation on a virtual machine, you can install OpenSearch manually via Tarball, or via the package manager (for RHEL-based distributions). For container deployment, you can install OpenSearch with Docker and Kubernetes.

In this example, you'll install OpenSearch on the containerized environment via Docker engine and Docker compose. So now, you'll be installing Docker packages from the official Docker repository.

To start, run the below apt command to install basic dependencies. Input y when prompted and press ENTER to proceed.

sudo apt install ca-certificates curl gnupg lsb-release

Output:

install basic dependencies

Next, run the below command to add the GPG key and repository for Docker packages.

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Output:

setup repo

After that, update and refresh your Ubuntu package index via the apt command below.

sudo apt update

Output:

update repo

With the Docker repository added, you can now install the Docker engine and Docker Compose plugin using the below apt command. When prompted, input y, then press ENTER to proceed.

sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin

Output:

install docker and docker compose

The Docker service will start and enable automatically. You can verify the Docker service via the following systemctl command utility.

sudo systemctl is-enabled docker
sudo systemctl status docker

You should get an output that the Docker service is enabled and will be run automatically at boot. And the status of the Docker service is running.

Lastly, to allow your non-root user to run the Docker container, you must add your user to the 'docker' group. Run the below usermod command below to add your user to the 'docker' group. Also, be sure to change the username with your user.

sudo usermod -aG docker alice

You can now log in as your user and run the Docker container via the below command.

su - alice
docker run hello-world

When successful, you should get the hello-world message from the Docker container like the following screenshot.

verify docker

Downloading OpenSearch Docker Images

In this step, you will download OpenSearch and OpenSearch Dashboards images from DockerHub. Then, you'll also run a new OpenSearch container for testing purposes.

Run the following command to download the OpenSearch and OpenSearch Dashboards images.

docker pull opensearchproject/opensearch:latest
docker pull opensearchproject/opensearch-dashboards:latest

Output:

download opensearch image

download opensearch dashboards

After downloads is finished, run the below command to check the list of Docker images on your system. You'll see the OpenSearch and OpenSearch Dashboards images is available on your system.

docker images

Output:

list images

Next, you can also run OpenSearch via Docker directly using the below command. This will create and run the OpenSearch container in a single mode and expose the default TCP port 9200 and 9600 on the host machine.

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

Verify the list of the running container via the 'docker ps' command below.

docker ps

You should receive an output like this - The OpenSearch container is created and it's running. Exposed TCP ports 9200 and 9600 on both the container and Docker host.

run container

You can access your OpenSearch container via the curl command below. The default username and password for the OpenSearch container is 'admin'.

curl https://localhost:9200 -ku 'admin:admin'

When successful, you should get an output like this - The OpenSearch container is running and accessible via the Docker host machine.

verify opensearch container

You can now run the below 'docker' command to stop and delete the OpenSearch container. Because in the next step, you will be creating an OpenSearch cluster via Docker Compose. Be sure to change the container name in the following command.

docker stop container-name or container-id
docker rm container-name or container-id

To ensure that the OpenSearch container is removed, run the 'docker ps' command with the additional option '-a'. This will show you available containers with both statuses, running and exited.

docker ps -a

Output:

remove container

Setup Project Directory

Log in to your user with the following command. This example uses a user 'alice', so be sure to change the username in the below command.

su - alice

Now create a new project directory 'opensearch-project' that will be used as the main root directory of your project, and the 'certs' directory that will be used to store custom TLS certificates.

mkdir -p ~/opensearch-project/certs; cd ~/opensearch-project

Within the 'opensearch-project' directory, run the below command to create new files that will be used to create OpenSearch containers and the OpenSearch Dashboards.

touch docker-compose.yml opensearch.yml opensearch_dashboards.yml internal_users.yml

setup project directory

The list of files:

  • docker-compose.yml - the main configuration of Docker Compose for the OpenSearch project.
  • opensearch.yml - custom configuration for OpenSearch containers.
  • opensearch_dashbaords.yml - custom configuration for OpenSearch Dashboards container.
  • internal_users.yml - custom user authentication and authorization for OpenSearch and OpenSearch Dashboards.

Generating SSL/TLS Certificates

In this step, you'll generate multiple TLS certificates that will be used to secure your OpenSearch deployment. You'll generate the following certificates:

  • Root CA certificates: These certificates will be used to sign other certificates.
  • Admin certificates: These certificates will be used to get administrative rights to perform all tasks related security plugin.
  • OpenSearch Dashboards certificates: These certificates will be used to secure the OpenSearch Dashboards and allows you can access OpenSearch Dashboards via HTTPS connections.
  • Node and Client Certificates: These certificates will be used by nodes and clients within the OpenSearch cluster.

To start, run the below command to create new directories that will be used for string TLS certificates.

mkdir -p certs/{ca,os-dashboards}

Create a new environment variable 'MYDN' that will be used to create new TLS certificates. Be sure to change the details with your information.

export MYDN="/C=CA/ST=ONTARIO/L=TORONTO/O=HWDOMAIN"

Now you're ready to generate TLS certificates for your OpenSearch deployment.

setup certs

Generate CA Certificates

Generate a private key for the root CA certificates using the below.

openssl genrsa -out certs/ca/ca.key 2048

Now generate a self-signed root CA certificate via the below command. The value of the '-subj' parameter is using the environment variable 'MYDN' that you've created on your current session.

openssl req -new -x509 -sha256 -days 1095 -subj "$MYDN/CN=CA" -key certs/ca/ca.key -out certs/ca/ca.pem

With this, you should get the root CA private key 'ca.key' and the root CA certificate 'ca.pem'. You can verify the CA certificates that you've generated via the following command.

ls certs/ca/

Output - You should get the CA private key 'ca.key' and the CA certificate 'ca.pem' file.

generate ca

Generate Admin Certificates

Generate the new admin certificate private key 'admin-temp.key' and convert the generated certificate to PKCS#12-compatible algorithm (3DES). With this, your admin private key should be 'admin.key'.

openssl genrsa -out certs/ca/admin-temp.key 2048
openssl pkcs8 -inform PEM -outform PEM -in certs/ca/admin-temp.key -topk8 -nocrypt -v1 PBE-SHA1-3DES -out certs/ca/admin.key

Next, run the below command to generate the admin CSR (Certificate Signing Request) from the 'admin.key' private key. Your generated CSR should now be 'admin.csr' file.

openssl req -new -subj "$MYDN/CN=ADMIN" -key certs/ca/admin.key -out certs/ca/admin.csr

Now run the below command to sign the admin CSR with the root CA certificate and private key. The output of the admin certificate is the 'admin.pem' file.

openssl x509 -req -in certs/ca/admin.csr -CA certs/ca/ca.pem -CAkey certs/ca/ca.key -CAcreateserial -sha256 -out certs/ca/admin.pem

Lastly, verify the list of your certificates via the following command.

ls certs/ca/

Output - You should see admin certificate files 'admin.pem' and private key 'admin.key'.

generate admin certificates

Generate OpenSearch Dashboards Certificates

Generate the new certificate that will be used for the OpenSearch Dashboards.

Run the following command to generate private key 'os-dashboards-temp.key' and convert the generated certificate to PKCS#12-compatible algorithm (3DES). With this, your admin private key should be 'os-dashboards.key'.

openssl genrsa -out certs/os-dashboards/os-dashboards-temp.key 2048
openssl pkcs8 -inform PEM -outform PEM -in certs/os-dashboards/os-dashboards-temp.key -topk8 -nocrypt -v1 PBE-SHA1-3DES -out certs/os-dashboards/os-dashboards.key

Next, run the below command to generate the CSR (Certificate Signing Request) for the OpenSearch Dashboards. Your generated CSR should now be the 'os-dashboards.csr' file.

openssl req -new -subj "$MYDN/CN=os-dashboards" -key certs/os-dashboards/os-dashboards.key -out certs/os-dashboards/os-dashboards.csr

Now run the below command to sign the OpenSearch Dashboards CSR with the root CA certificate and private key. The output of the admin certificate is the 'os-dashboards.pem' file.

openssl x509 -req -in certs/os-dashboards/os-dashboards.csr -CA certs/ca/ca.pem -CAkey certs/ca/ca.key -CAcreateserial -sha256 -out certs/os-dashboards/os-dashboards.pem

Lastly, run the following command to delete the OpenSearch Dashboards CSR file and verify the list of your certificates for the OpenSearch Dashboards.

rm certs/os-dashboards/os-dashboards-temp.key cert