import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PartialOpenSearchAuthMode from '@site/docs/_partial-opensearch-auth-mode.mdx';

You can use either **Basic Setup** or **Advanced Setup** to configure OpenRAG.
This choice determines how OpenRAG authenticates with your deployment's [OpenSearch instance](/knowledge), and it controls user access to documents stored in your OpenSearch knowledge base:

<PartialOpenSearchAuthMode />

:::info
You must use **Advanced Setup** if you want to [use OAuth connectors to upload documents from cloud storage](/ingestion#oauth-ingestion).
:::

If OpenRAG detects OAuth credentials during setup, it recommends **Advanced Setup** in the TUI.

<Tabs groupId="Setup method">
<TabItem value="Basic setup" label="Basic setup" default>

1. In the TUI, click **Basic Setup** or press <kbd>1</kbd>.

2. Enter administrator passwords for the OpenRAG OpenSearch and Langflow services, or click **Generate Passwords** to generate passwords automatically.

   The OpenSearch password is required.

   The Langflow password is recommended but optional.
   If the Langflow password is empty, the Langflow server starts without authentication enabled. For more information, see [Langflow settings](/reference/configuration#langflow-settings).

3. Optional: Enter your OpenAI API key, or leave this field empty to provide model provider credentials during the application onboarding process.

   There is no material difference between providing the key now or during the [application onboarding process](#application-onboarding).
   If you provide a key now, it can be populated automatically during the application onboarding process if you select the OpenAI model provider, and then enable **Get API key from environment variable**.

   OpenRAG's core functionality requires access to language and embedding models.
   By default, OpenRAG uses OpenAI models.
   If you aren't sure which models or providers to use, you must provide an OpenAI API key to use OpenRAG's default model configuration.
   If you want to use a different model provider, you can leave this field empty.

4. Click **Save Configuration**.

   Your passwords and API key, if provided, are stored in the [OpenRAG `.env` file](/reference/configuration) in your OpenRAG installation directory.
   If you modified any credentials that were pulled from an existing `.env` file, those values are updated in the `.env` file.

5. Click **Start All Services** to start the OpenRAG services that run in containers.

   This process can take some time while OpenRAG pulls and runs the container images.
   If all services start successfully, the TUI prints a confirmation message:

   ```text
   Services started successfully
   Command completed successfully
   ```

6. Under [**Native Services**](/manage-services), click **Start** to start the Docling service.

7. Launch the OpenRAG application:

   * From the TUI main menu, click **Open App**.
   * In your browser, navigate to `localhost:3000`.

8. Continue with the [application onboarding process](#application-onboarding).

</TabItem>
<TabItem value="Advanced setup" label="Advanced setup">

1. In the TUI, click **Advanced Setup** or press <kbd>2</kbd>.

2. Enter administrator passwords for the OpenRAG OpenSearch and Langflow services, or click **Generate Passwords** to generate passwords automatically.

   The OpenSearch password is required.

   The Langflow password is recommended but optional.
   If the Langflow password is empty, the Langflow server starts without authentication enabled. For more information, see [Langflow settings](/reference/configuration#langflow-settings).

3. Optional: Enter your OpenAI API key, or leave this field empty to provide model provider credentials during the application onboarding process.

   There is no material difference between providing the key now or during the [application onboarding process](#application-onboarding).
   If you provide a key now, it can be populated automatically during the application onboarding process if you select the OpenAI model provider, and then enable **Get API key from environment variable**.

   OpenRAG's core functionality requires access to language and embedding models.
   By default, OpenRAG uses OpenAI models.
   If you aren't sure which models or providers to use, you must provide an OpenAI API key to use OpenRAG's default model configuration.
   If you want to use a different model provider, you can leave this field empty.

4. To upload documents from external storage, such as Google Drive, add the required OAuth credentials for the connectors that you want to use. These settings can be populated automatically if OpenRAG detects these credentials in an [OpenRAG `.env` file](/reference/configuration) in the OpenRAG installation directory.

   * **Amazon**: Provide your AWS Access Key ID and AWS Secret Access Key with access to your S3 instance. For more information, see the AWS documentation on [Configuring access to AWS applications](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-applications.html).
   * **Google**: Provide your Google OAuth Client ID and Google OAuth Client Secret. You can generate these in the [Google Cloud Console](https://console.cloud.google.com/apis/credentials). For more information, see the [Google OAuth client documentation](https://developers.google.com/identity/protocols/oauth2).
   * **Microsoft**: For the Microsoft OAuth Client ID and Microsoft OAuth Client Secret, provide [Azure application registration credentials for SharePoint and OneDrive](https://learn.microsoft.com/en-us/onedrive/developer/rest-api/getting-started/app-registration?view=odsp-graph-online). For more information, see the [Microsoft Graph OAuth client documentation](https://learn.microsoft.com/en-us/onedrive/developer/rest-api/getting-started/graph-oauth).

   You can [manage OAuth credentials](/ingestion#oauth-ingestion) later, but it is recommended to configure them during initial set up.

5. The OpenRAG TUI presents redirect URIs for your OAuth app.
These are the URLs your OAuth provider will redirect back to after user sign-in.
Register these redirect values with your OAuth provider as they are presented in the TUI.

6. Click **Save Configuration**.

   Your passwords, API key, and OAuth credentials, if provided, are stored in the [OpenRAG `.env` file](/reference/configuration) in your OpenRAG installation directory.
   If you modified any credentials that were pulled from an existing `.env` file, those values are updated in the `.env` file.

7. Click **Start All Services** to start the OpenRAG services that run in containers.

   This process can take some time while OpenRAG pulls and runs the container images.
   If all services start successfully, the TUI prints a confirmation message:

   ```text
   Services started successfully
   Command completed successfully
   ```

8. Under [**Native Services**](/manage-services), click **Start** to start the Docling service.

9. Launch the OpenRAG application:

   * From the TUI main menu, click **Open App**.
   * In your browser, navigate to `localhost:3000`.

10. If you enabled OAuth connectors, you must sign in to your OAuth provider before being redirected to your OpenRAG instance.

11. If required, you can edit the following additional environment variables.
Only change these variables if your OpenRAG deployment has a non-default network configuration, such as a reverse proxy or custom domain.

      * `LANGFLOW_PUBLIC_URL`: Sets the base address to access the Langflow web interface. This is where users interact with flows in a browser.
      * `WEBHOOK_BASE_URL`: Sets the base address for the following OpenRAG OAuth connector endpoints:
         * Amazon S3: Not applicable.
         * Google Drive: `WEBHOOK_BASE_URL/connectors/google_drive/webhook`
         * OneDrive: `WEBHOOK_BASE_URL/connectors/onedrive/webhook`
         * SharePoint: `WEBHOOK_BASE_URL/connectors/sharepoint/webhook`

12. Continue with the [application onboarding process](#application-onboarding).

</TabItem>
</Tabs>

<!-- Author's note: Under Advanced Setup, the bullets for `LANGFLOW_PUBLIC_URL` and `WEBHOOK_BASE_URL` must be indented extra spaces in order to render correctly. Not sure why, but please don't outdent them unless you can enforce the rendering. -->