> ## Documentation Index
> Fetch the complete documentation index at: https://danswer-whuang-craft-v2-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenSearch

> Configuring Onyx with OpenSearch

## Overview

OpenSearch is the document index Onyx uses for retrieval.

In Onyx’s **Helm** chart, we maintain a section which defines the desired setup for an instance of OpenSearch,
and another section which defines auth for that instance. If these are enabled (the default as of `v3`),
when you start your Onyx instance using Helm,
Helm will also start the OpenSearch instance (containing one or more containers)
and seed the appropriate auth values throughout the application.
By default the OpenSearch instance will have only one container.

Additionally, the Onyx application itself needs to know that OpenSearch is enabled,
and how to connect to the OpenSearch instance. In the configmap template that the Onyx Helm chart tracks,
if the OpenSearch section mentioned above is enabled (the default as of `v3`),
the environment variables for the OpenSearch host, port, and whether it is enabled at all,
will be set throughout the application.

In Onyx's **docker-compose** file, the `opensearch` service defines both the desired setup and auth.
Rather than a configmap as in Helm, the application just reads environment variables that you can set in a `.env` file.

## Auth

Unless explicitly disabled,
OpenSearch requires setting initial credentials for the cluster which are used to authenticate all requests.
The password must meet certain complexity requirements: minimum 8 chars, at least one uppercase, lowercase, digit,
and special character.

If using Onyx's **docker-compose**,
there is no action necessarily required as the compose file supplies a default initial password which matches the
default value Onyx falls back to in the absence of the relevant env var `OPENSEARCH_ADMIN_PASSWORD`.

If you wish to set this password to some other value, set an env var `OPENSEARCH_ADMIN_PASSWORD` to your desired string,
ensure `docker` references this env var when running `docker-compose`,
and also ensure this env var is in a `.env` file Onyx references as well.

If using **Helm**,
there is no default password and some password must be specified in the `values.yaml` file specified in your Helm
command as shown:

```yaml values.yaml theme={null}
# Other overrides you may have.

configMap:
  # Other overrides you may have.

  OPENSEARCH_ADMIN_PASSWORD: <your chosen password>

auth:
  # Other overrides you may have.

  opensearch:
   values:
     opensearch_admin_password: <your chosen password>
```

## If using your own provisioned managed OpenSearch

[If you provisioned a managed instance](/deployment/local/terraform#opensearch-optional),
you do not need Helm to start an OpenSearch container/cluster for you.
You can disable this in your Helm values `yaml` file.

```yaml values.yaml theme={null}
# Other overrides you may have.

opensearch:
  enabled: false

auth:
  # Other overrides you may have.

  opensearch:
    enabled: false
```

You also need to specify what the intended environment variables should be, based on the OpenSearch cluster.
These variables will be propagated throughout the Onyx application.

```yaml values.yaml theme={null}
# Other overrides you may have.

configMap:
  # Other overrides you may have.

  OPENSEARCH_ADMIN_USERNAME: "<the username you set when creating the OpenSearch cluster>"
  OPENSEARCH_ADMIN_PASSWORD: "<the password you set when creating the OpenSearch cluster>"
  OPENSEARCH_HOST: "<the host name of the OpenSearch cluster, as reported on the AWS console; do not include https://>"
  OPENSEARCH_REST_API_PORT: "443"
  USING_AWS_MANAGED_OPENSEARCH: "true"
```