openrag/docs/docs/get-started/docker.mdx

---
title: Deploy OpenRAG with self-managed services
slug: /docker
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PartialOnboarding from '@site/docs/_partial-onboarding.mdx';
import PartialPrereqCommon from '@site/docs/_partial-prereq-common.mdx';
import PartialPrereqNoScript from '@site/docs/_partial-prereq-no-script.mdx';
import PartialPrereqWindows from '@site/docs/_partial-prereq-windows.mdx';
import PartialPrereqPython from '@site/docs/_partial-prereq-python.mdx';
import PartialInstallNextSteps from '@site/docs/_partial-install-next-steps.mdx';
import PartialOllamaModels from '@site/docs/_partial-ollama-models.mdx';

To manage your own OpenRAG services, deploy OpenRAG with Docker or Podman.

Use this installation method if you don't want to [use the Terminal User Interface (TUI)](/tui), or you need to run OpenRAG in an environment where using the TUI is unfeasible.

## Prerequisites

<PartialPrereqWindows />

<PartialPrereqPython />

<PartialPrereqNoScript />

<PartialPrereqCommon />

## Prepare your deployment {#setup}

1. Clone the OpenRAG repository:

   ```bash
   git clone https://github.com/langflow-ai/openrag.git
   ```

2. Change to the root of the cloned repository:

   ```bash
   cd openrag
   ```

3. Install dependencies:

   ```bash
   uv sync
   ```

4. Create a `.env` file at the root of the cloned repository.

   You can create an empty file or copy the repository's [`.env.example`](https://github.com/langflow-ai/openrag/blob/main/.env.example) file.
   The example file contains some of the [OpenRAG environment variables](/reference/configuration) to get you started with configuring your deployment.

   ```bash
   cp .env.example .env
   ```

5. Edit the `.env` file to configure your deployment using [OpenRAG environment variables](/reference/configuration).
The OpenRAG Docker Compose files pull values from your `.env` file to configure the OpenRAG containers.
The following variables are required or recommended:

   * **`OPENSEARCH_PASSWORD` (Required)**: Sets the OpenSearch administrator password. It must adhere to the [OpenSearch password complexity requirements](https://docs.opensearch.org/latest/security/configuration/demo-configuration/#setting-up-a-custom-admin-password).

   * **`LANGFLOW_SUPERUSER`**: The username for the Langflow administrator user. If `LANGFLOW_SUPERUSER` isn't set, then the default value is `admin`.

   * **`LANGFLOW_SUPERUSER_PASSWORD` (Strongly recommended)**: Sets the Langflow administrator password, and determines the Langflow server's default authentication mode. If `LANGFLOW_SUPERUSER_PASSWORD` isn't set, then the Langflow server starts without authentication enabled. For more information, see [Langflow settings](/reference/configuration#langflow-settings).

   * **`LANGFLOW_SECRET_KEY` (Strongly recommended)**: A secret encryption key for internal Langflow operations. It is recommended to [generate your own Langflow secret key](https://docs.langflow.org/api-keys-and-authentication#langflow-secret-key). If `LANGFLOW_SECRET_KEY` isn't set, then Langflow generates a secret key automatically.

   * **Model provider credentials**: Provide credentials for your preferred model providers. If none of these are set in the `.env` file, you must configure at least one provider during the [application onboarding process](#application-onboarding).

      * `OPENAI_API_KEY`
      * `ANTHROPIC_API_KEY`
      * `OLLAMA_ENDPOINT`
      * `WATSONX_API_KEY`
      * `WATSONX_ENDPOINT`
      * `WATSONX_PROJECT_ID`

   * **OAuth provider credentials**: To upload documents from external storage, such as Google Drive, set the required OAuth credentials for the connectors that you want to use. You can [manage OAuth credentials](/ingestion#oauth-ingestion) later, but it is recommended to configure them during initial set up so you don't have to rebuild the containers.

      * **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).

   For more information and variables, see [OpenRAG environment variables](/reference/configuration).

## Start services

1. Start `docling serve` on port 5001 on the host machine:

   ```bash
   uv run python scripts/docling_ctl.py start --port 5001
   ```

   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
   ```

   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
   Docs: http://127.0.0.1:5001/docs
   PID: 27746
   ```

3. Deploy the OpenRAG containers locally using the appropriate Docker Compose configuration for your environment.

   * **GPU-accelerated deployment**: If your host machine has an NVIDIA GPU with CUDA support and compatible NVIDIA drivers, use the base `docker-compose.yml` file with the `docker-compose.gpu.yml` override.

      ```bash title="Docker"
      docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d
      ```

      ```bash title="Podman"
      podman compose -f docker-compose.yml -f docker-compose.gpu.yml up -d
      ```

   * **CPU-only deployment** (default): If your host machine doesn't have NVIDIA GPU support, use the base `docker-compose.yml` file.

      ```bash title="Docker"
      docker compose up -d
      ```

      ```bash title="Podman"
      podman compose up -d
      ```

4. Wait for the OpenRAG containers to start, and then confirm that all containers are running:

   ```bash title="Docker"
   docker compose ps
   ```

   ```bash title="Podman"
   podman compose ps
   ```

   The OpenRAG Docker Compose files deploy the following 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. |

   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 the [application onboarding process](#application-onboarding).

<PartialOnboarding />

<PartialInstallNextSteps />