diff --git a/docs/docs/_partial-setup.mdx b/docs/docs/_partial-setup.mdx index 056e58dd..c33833d6 100644 --- a/docs/docs/_partial-setup.mdx +++ b/docs/docs/_partial-setup.mdx @@ -11,106 +11,106 @@ You must use **Advanced Setup** if you want to [use OAuth connectors to upload d If OpenRAG detects OAuth credentials during setup, it recommends **Advanced Setup** in the TUI. - + - 1. In the TUI, click **Basic Setup** or press 1. +1. In the TUI, click **Basic Setup** or press 1. - 2. Enter administrator passwords for the OpenRAG OpenSearch and Langflow services, or click **Generate Passwords** to generate passwords automatically. +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 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). + 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 if you want to configure model provider credentials later during application onboarding. +3. Optional: Enter your OpenAI API key, or leave this field empty if you want to configure model provider credentials later during application onboarding. - 4. Click **Save Configuration**. +4. Click **Save Configuration**. - Your passwords and API key, if provided, are stored in the `.env` file 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. + Your passwords and API key, if provided, are stored in the `.env` file 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. +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: + 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 - ``` + ```text + Services started successfully + Command completed successfully + ``` - 6. Under [**Native Services**](/manage-services), click **Start** to start the Docling service. +6. Under [**Native Services**](/manage-services), click **Start** to start the Docling service. - 7. Launch the OpenRAG application: +7. Launch the OpenRAG application: - * From the TUI main menu, click **Open App**. - * In your browser, navigate to `localhost:3000`. + * From the TUI main menu, click **Open App**. + * In your browser, navigate to `localhost:3000`. - 8. Continue with [application onboarding](#application-onboarding). +8. Continue with [application onboarding](#application-onboarding). - - + + - 1. In the TUI, click **Advanced Setup** or press 2. +1. In the TUI, click **Advanced Setup** or press 2. - 2. Enter administrator passwords for the OpenRAG OpenSearch and Langflow services, or click **Generate Passwords** to generate passwords automatically. +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 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). + 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 if you want to configure model provider credentials later during application onboarding. +3. Optional: Enter your OpenAI API key, or leave this field empty if you want to configure model provider credentials later during application onboarding. - 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 a `.env` file in the OpenRAG installation directory. +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 a `.env` file 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). + * **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. + 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. +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**. +6. Click **Save Configuration**. - Your passwords, API key, and OAuth credentials, if provided, are stored in the `.env` file 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. + Your passwords, API key, and OAuth credentials, if provided, are stored in the `.env` file 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. +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: + 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 - ``` + ```text + Services started successfully + Command completed successfully + ``` - 8. Under [**Native Services**](/manage-services), click **Start** to start the Docling service. +8. Under [**Native Services**](/manage-services), click **Start** to start the Docling service. - 9. Launch the OpenRAG application: +9. Launch the OpenRAG application: - * From the TUI main menu, click **Open App**. - * In your browser, navigate to `localhost:3000`. + * 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. +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. +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. + * `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: + * `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` + * 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 [application onboarding](#application-onboarding). +12. Continue with [application onboarding](#application-onboarding). - + \ No newline at end of file diff --git a/docs/docs/core-components/ingestion.mdx b/docs/docs/core-components/ingestion.mdx index 78f9bbbf..d5210fcf 100644 --- a/docs/docs/core-components/ingestion.mdx +++ b/docs/docs/core-components/ingestion.mdx @@ -228,6 +228,7 @@ All errors were file-specific, and they didn't stop the pipeline. * Machine: Apple M4 Pro * Podman VM: + * Name: podman-machine-default * Type: applehv * vCPUs: 7 diff --git a/docs/docs/get-started/docker.mdx b/docs/docs/get-started/docker.mdx index c204baf8..e5ea9673 100644 --- a/docs/docs/get-started/docker.mdx +++ b/docs/docs/get-started/docker.mdx @@ -82,22 +82,30 @@ The following variables are required or recommended: * **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). - For more information and variables, see [Environment variables](/reference/configuration). + For more information and variables, see [OpenRAG environment variables](/reference/configuration). -6. Start `docling serve` on the host machine. - OpenRAG Docker installations require that `docling serve` is running on port 5001 on the host machine. - This enables [Mac MLX](https://opensource.apple.com/projects/mlx/) support for document processing. +## Start services + +1. Start `docling serve` on port 5001 on the host machine: ```bash uv run python scripts/docling_ctl.py start --port 5001 ``` -7. Confirm `docling serve` is running. - ``` + Docling cannot run inside a Docker container due to system-level dependencies, so you must manage it as a separate service on the host machine. + For more information, see [Stop, start, and inspect native services](/manage-services#start-native-services). + + This port is required to deploy OpenRAG successfully; don't use a different port. + Additionally, this enables the [MLX framework](https://opensource.apple.com/projects/mlx/) for accelerated performance on Apple Silicon Mac machines. + +2. Confirm `docling serve` is running. + + ```bash uv run python scripts/docling_ctl.py status ``` - Make sure the response shows that `docling serve` is running, for example: + If `docling serve` is running, the output includes the status, address, and process ID (PID): + ```bash Status: running Endpoint: http://127.0.0.1:5001 @@ -105,10 +113,10 @@ The following variables are required or recommended: PID: 27746 ``` -8. Deploy OpenRAG locally with the appropriate Docker Compose file for your environment. +3. Deploy the OpenRAG containers locally using the appropriate Docker Compose file for your environment. Both files deploy the same services. - * [`docker-compose.yml`](https://github.com/langflow-ai/openrag/blob/main/docker-compose.yml) is an OpenRAG deployment with GPU support for accelerated AI processing. This Docker Compose file requires an NVIDIA GPU with [CUDA](https://docs.nvidia.com/cuda/) support. + * [`docker-compose.yml`](https://github.com/langflow-ai/openrag/blob/main/docker-compose.yml): If your host machine has an NVIDIA GPU with CUDA support and compatible NVIDIA drivers, you can use this file to deploy OpenRAG with accelerated processing. * Docker: @@ -124,7 +132,7 @@ Both files deploy the same services. podman compose up -d ``` - * [`docker-compose-cpu.yml`](https://github.com/langflow-ai/openrag/blob/main/docker-compose-cpu.yml) is a CPU-only version of OpenRAG for systems without NVIDIA GPU support. Use this Docker Compose file for environments where GPU drivers aren't available. + * [`docker-compose-cpu.yml`](https://github.com/langflow-ai/openrag/blob/main/docker-compose-cpu.yml): If your host machine doesn't have NVIDIA GPU support, use this file for a CPU-only OpenRAG deployment. * Docker: @@ -138,17 +146,7 @@ Both files deploy the same services. podman compose -f docker-compose-cpu.yml up -d ``` - The OpenRAG Docker Compose file starts five containers: - - | Container Name | Default address | Purpose | - |---|---|---| - | OpenRAG Backend | http://localhost:8000 | FastAPI server and core functionality. | - | OpenRAG Frontend | http://localhost:3000 | React web interface for user interaction. | - | Langflow | http://localhost:7860 | [AI workflow engine](/agents). | - | OpenSearch | http://localhost:9200 | Datastore for [knowledge](/knowledge). | - | OpenSearch Dashboards | http://localhost:5601 | OpenSearch database administration interface. | - -9. Wait while the containers start, and then confirm all containers are running: +4. Wait for the OpenRAG containers to start, and then confirm that all containers are running: * Docker Compose: @@ -162,9 +160,19 @@ Both files deploy the same services. podman compose ps ``` - If all containers are running, you can access your OpenRAG services at their addresses. + The OpenRAG Docker Compose files deploy the following containers: -10. Access the OpenRAG frontend at `http://localhost:3000` to continue with [application onboarding](#application-onboarding). + | Container Name | Default address | Purpose | + |---|---|---| + | OpenRAG Backend | http://localhost:8000 | FastAPI server and core functionality. | + | OpenRAG Frontend | http://localhost:3000 | React web interface for user interaction. | + | Langflow | http://localhost:7860 | [AI workflow engine](/agents). | + | OpenSearch | http://localhost:9200 | Datastore for [knowledge](/knowledge). | + | OpenSearch Dashboards | http://localhost:5601 | OpenSearch database administration interface. | + + When the containers are running, you can access your OpenRAG services at their addresses. + +5. Access the OpenRAG frontend at `http://localhost:3000`, and then continue with [application onboarding](#application-onboarding). diff --git a/docs/docs/get-started/install-options.mdx b/docs/docs/get-started/install-options.mdx index db72673a..feca2b70 100644 --- a/docs/docs/get-started/install-options.mdx +++ b/docs/docs/get-started/install-options.mdx @@ -10,9 +10,9 @@ Select the installation method that best fits your needs: * **Use the [Terminal User Interface (TUI)](/tui) to manage services**: For guided configuration and simplified service management, install OpenRAG with TUI-managed services. - * [**Automatic installer script**](/install): Run one script to install the required dependencies and OpenRAG. - * [**`uv`**](/install-uv): Install OpenRAG as a dependency of a new or existing Python project. - * [**`uvx`**](/install-uvx): Install OpenRAG without creating a project or modifying your project's dependencies. + * [**Automatic installer script**](/install): Run one script to install the required dependencies and OpenRAG. + * [**`uv`**](/install-uv): Install OpenRAG as a dependency of a new or existing Python project. + * [**`uvx`**](/install-uvx): Install OpenRAG without creating a project or modifying your project's dependencies. * [**Install OpenRAG on Microsoft Windows**](/install-windows): On Windows machines, you must install OpenRAG within the Windows Subsystem for Linux (WSL). diff --git a/docs/docs/get-started/install-uv.mdx b/docs/docs/get-started/install-uv.mdx index 5c94da6d..a1d6bd83 100644 --- a/docs/docs/get-started/install-uv.mdx +++ b/docs/docs/get-started/install-uv.mdx @@ -44,46 +44,46 @@ If you encounter errors during installation, see [Troubleshoot OpenRAG](/support 1. Create a new `uv`-managed Python project: - ```bash - uv init PROJECT_NAME - ``` + ```bash + uv init PROJECT_NAME + ``` 2. Change into your new project directory: - ```bash - cd PROJECT_NAME - ``` + ```bash + cd PROJECT_NAME + ``` - Because `uv` manages the virtual environment for you, you won't see a `(venv)` prompt. - `uv` commands automatically use the project's virtual environment. + Because `uv` manages the virtual environment for you, you won't see a `(venv)` prompt. + `uv` commands automatically use the project's virtual environment. 2. Add OpenRAG to your project: * Add the latest version: - ```bash - uv add openrag - ``` + ```bash + uv add openrag + ``` * Add a specific version: - ```bash - uv add openrag==0.1.30 - ``` + ```bash + uv add openrag==0.1.30 + ``` * Add a local wheel: - ```bash - uv add path/to/openrag-VERSION-py3-none-any.whl - ``` + ```bash + uv add path/to/openrag-VERSION-py3-none-any.whl + ``` - For more options, see [Managing dependencies with `uv`](https://docs.astral.sh/uv/concepts/projects/dependencies/). + For more options, see [Managing dependencies with `uv`](https://docs.astral.sh/uv/concepts/projects/dependencies/). 3. Start the OpenRAG TUI: - ```bash - uv run openrag - ``` + ```bash + uv run openrag + ``` ### uv pip install {#uv-pip-install} @@ -91,15 +91,15 @@ If you encounter errors during installation, see [Troubleshoot OpenRAG](/support 2. Install the OpenRAG Python package: - ```bash - uv pip install openrag - ``` + ```bash + uv pip install openrag + ``` 3. Start the OpenRAG TUI: - ```bash - uv run openrag - ``` + ```bash + uv run openrag + ``` ## Set up OpenRAG with the TUI {#setup} diff --git a/docs/docs/get-started/uninstall.mdx b/docs/docs/get-started/uninstall.mdx index 0cb0eda1..cad6e998 100644 --- a/docs/docs/get-started/uninstall.mdx +++ b/docs/docs/get-started/uninstall.mdx @@ -45,9 +45,9 @@ For self-managed services, destroy the containers, prune any additional Docker o 3. Stop `docling-serve`: - ```bash - uv run python scripts/docling_ctl.py stop - ``` + ```bash + uv run python scripts/docling_ctl.py stop + ``` ### Step-by-step removal and cleanup with Docker or Podman @@ -147,6 +147,6 @@ Use these commands for step-by-step container removal and cleanup: 8. Stop `docling-serve`: - ```bash - uv run python scripts/docling_ctl.py stop - ``` \ No newline at end of file + ```bash + uv run python scripts/docling_ctl.py stop + ``` \ No newline at end of file diff --git a/docs/docs/support/troubleshoot.mdx b/docs/docs/support/troubleshoot.mdx index cea55b7d..ef386158 100644 --- a/docs/docs/support/troubleshoot.mdx +++ b/docs/docs/support/troubleshoot.mdx @@ -50,7 +50,14 @@ podman machine start ## Port conflicts -Ensure ports 3000, 7860, 8000, 9200, 5601 are available. +With the default [configuration](/reference/configuration), OpenRAG requires the following ports to be available on the host machine: + +* 3000: Langflow application +* 5001: Docling local ingestion service +* 5601: OpenSearch Dashboards +* 7860: Docling UI +* 8000: Docling API +* 9200: OpenSearch service ## OCR ingestion fails (easyocr not installed)