> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onyx.app/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"
```