---
title: Install OpenRAG containers
slug: /docker
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PartialOnboarding from '@site/docs/_partial-onboarding.mdx';

OpenRAG has two Docker Compose files. Both files deploy the same applications and containers locally, but they are for different environments.

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

## Prerequisites

- Install [Python Version 3.10 to 3.13](https://www.python.org/downloads/release/python-3100/)
- Install [uv](https://docs.astral.sh/uv/getting-started/installation/)
- Install [Podman](https://podman.io/docs/installation) (recommended) or [Docker](https://docs.docker.com/get-docker/)
- Install [Docker Compose](https://docs.docker.com/compose/install/). If using Podman, use [podman-compose](https://docs.podman.io/en/latest/markdown/podman-compose.1.html) or alias Docker compose commands to Podman commands.
- Optional: Create an [OpenAI API key](https://platform.openai.com/api-keys). You can provide this key during [Application Onboarding](#application-onboarding) or choose a different model provider.
- Optional: Install GPU support with an NVIDIA GPU, [CUDA](https://docs.nvidia.com/cuda/) support, and compatible NVIDIA drivers on the OpenRAG host machine. If you don't have GPU capabilities, OpenRAG provides an alternate CPU-only deployment.

## Install OpenRAG with Docker Compose

To install OpenRAG with Docker Compose, do the following:

1. Clone the OpenRAG repository.
   ```bash
   git clone https://github.com/langflow-ai/openrag.git
   cd openrag
   ```

2. Install dependencies.
   ```bash
   uv sync
   ```

3. Copy the example `.env` file included in the repository root.
  The example file includes all environment variables with comments to guide you in finding and setting their values.
   ```bash
   cp .env.example .env
   ```

   Alternatively, create a new `.env` file in the repository root.
   ```
   touch .env
   ```

4. The Docker Compose files are populated with the values from your `.env` file. 
   The `OPENSEARCH_PASSWORD` value must be set.
   `OPENSEARCH_PASSWORD` can be automatically generated when using the TUI, but for a Docker Compose installation, you can set it manually instead. To generate an OpenSearch admin password, see the [OpenSearch documentation](https://docs.opensearch.org/latest/security/configuration/demo-configuration/#setting-up-a-custom-admin-password).

   The following values are optional:

   ```bash
   OPENAI_API_KEY=your_openai_api_key
   LANGFLOW_SECRET_KEY=your_secret_key
   ```

   `OPENAI_API_KEY` is optional. You can provide it during [Application Onboarding](#application-onboarding) or choose a different model provider. If you want to set it in your `.env` file, you can find your OpenAI API key in your [OpenAI account](https://platform.openai.com/api-keys).

   `LANGFLOW_SECRET_KEY` is optional. Langflow will auto-generate it if not set. For more information, see the [Langflow documentation](https://docs.langflow.org/api-keys-and-authentication#langflow-secret-key).

   The following Langflow configuration values are optional but important to consider:

   ```bash
   LANGFLOW_SUPERUSER=admin
   LANGFLOW_SUPERUSER_PASSWORD=your_langflow_password
   ```

   `LANGFLOW_SUPERUSER` defaults to `admin`. You can omit it or set it to a different username. `LANGFLOW_SUPERUSER_PASSWORD` is optional. If omitted, Langflow runs in [autologin mode](https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login) with no password required. If set, Langflow requires password authentication.
   
   For more information on configuring OpenRAG with environment variables, see [Environment variables](/reference/configuration).

5. 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.
   
   ```bash
   uv run python scripts/docling_ctl.py start --port 5001
   ```
   
6. Confirm `docling serve` is running.
   ```
   uv run python scripts/docling_ctl.py status
   ```

   Make sure the response shows that `docling serve` is running, for example:
   ```bash
   Status: running
   Endpoint: http://127.0.0.1:5001
   Docs: http://127.0.0.1:5001/docs
   PID: 27746
   ```

7. Deploy OpenRAG locally with Docker Compose based on your deployment type.

   <Tabs groupId="Compose file">
     <TabItem value="docker-compose.yml" label="docker-compose.yml" default>
   ```bash
   docker compose build
   docker compose up -d
   ```   
     </TabItem>
     <TabItem value="docker-compose-cpu.yml" label="docker-compose-cpu.yml">
   
   ```bash
   docker compose -f docker-compose-cpu.yml up -d
   ```
   
     </TabItem>
   </Tabs>

   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 users. |
   | Langflow | http://localhost:7860 | AI workflow engine and flow management. |
   | OpenSearch | http://localhost:9200 | Vector database for document storage. |
   | OpenSearch Dashboards | http://localhost:5601 | Database administration interface. |

8. Verify installation by confirming all services are running.

   ```bash
   docker compose ps
   ```

   You can now access OpenRAG at the following endpoints:

   - **Frontend**: http://localhost:3000
   - **Backend API**: http://localhost:8000
   - **Langflow**: http://localhost:7860

9. Continue with [Application Onboarding](#application-onboarding).

To stop `docling serve` when you're done with your OpenRAG deployment, run:

```bash
uv run python scripts/docling_ctl.py stop
```

<PartialOnboarding />

## Container management commands

Manage your OpenRAG containers with the following commands.
These commands are also available in the TUI's [Status menu](/install#status).

### Upgrade containers

Upgrade your containers to the latest version while preserving your data.

```bash
docker compose pull
docker compose up -d --force-recreate
```

### Rebuild containers (destructive)

Reset state by rebuilding all of your containers.
Your OpenSearch and Langflow databases will be lost.
Documents stored in the `./documents` directory will persist, since the directory is mounted as a volume in the OpenRAG backend container.

```bash
docker compose up --build --force-recreate --remove-orphans
```

### Remove all containers and data (destructive)

Completely remove your OpenRAG installation and delete all data.
This deletes all of your data, including OpenSearch data, uploaded documents, and authentication. 
```bash
docker compose down --volumes --remove-orphans --rmi local
docker system prune -f
```