358 lines
No EOL
12 KiB
Text
358 lines
No EOL
12 KiB
Text
---
|
|
title: Install OpenRAG containers
|
|
slug: /docker
|
|
---
|
|
|
|
import Tabs from '@theme/Tabs';
|
|
import TabItem from '@theme/TabItem';
|
|
import PartialOnboarding from '@site/docs/_partial-onboarding.mdx';
|
|
import PartialWsl from '@site/docs/_partial-wsl-install.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 the following:
|
|
|
|
- [Python](https://www.python.org/downloads/release/python-3100/) version 3.13 or later.
|
|
- [uv](https://docs.astral.sh/uv/getting-started/installation/).
|
|
- [Podman](https://podman.io/docs/installation) (recommended) or [Docker](https://docs.docker.com/get-docker/).
|
|
- [`podman-compose`](https://docs.podman.io/en/latest/markdown/podman-compose.1.html) or [Docker Compose](https://docs.docker.com/compose/install/). To use Docker Compose with Podman, you must alias Docker Compose commands to Podman commands.
|
|
|
|
- Microsoft Windows only: To run OpenRAG on Windows, you must use the Windows Subsystem for Linux (WSL).
|
|
|
|
<details>
|
|
<summary>Install WSL for OpenRAG</summary>
|
|
|
|
<PartialWsl />
|
|
|
|
</details>
|
|
|
|
- Prepare model providers and credentials.
|
|
|
|
During [application onboarding](#application-onboarding), you must select language model and embedding model providers.
|
|
If your chosen provider offers both types, you can use the same provider for both selections.
|
|
If your provider offers only one type, such as Anthropic, you must select two providers.
|
|
|
|
Gather the credentials and connection details for your chosen model providers before starting onboarding:
|
|
|
|
- OpenAI: Create an [OpenAI API key](https://platform.openai.com/api-keys).
|
|
- Anthropic language models: Create an [Anthropic API key](https://www.anthropic.com/docs/api/reference).
|
|
- IBM watsonx.ai: Get your watsonx.ai API endpoint, IBM project ID, and IBM API key from your watsonx deployment.
|
|
- Ollama: Use the [Ollama documentation](https://docs.ollama.com/) to set up your Ollama instance locally, in the cloud, or on a remote server, and then get your Ollama server's base URL.
|
|
|
|
- Optional: Install GPU support with an NVIDIA GPU, [CUDA](https://docs.nvidia.com/cuda/) support, and compatible NVIDIA drivers on the OpenRAG host machine. This is required to use the GPU-accelerated Docker Compose file. If you choose not to use GPU support, you must use the CPU-only Docker Compose file instead.
|
|
|
|
## 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-containers}
|
|
|
|
Upgrade your containers to the latest version while preserving your data.
|
|
|
|
```bash
|
|
docker compose pull
|
|
docker compose up -d --force-recreate
|
|
```
|
|
|
|
### Reset containers (destructive) {#reset-containers}
|
|
|
|
:::warning
|
|
These are destructive operations that reset your OpenRAG deployment to an initial state.
|
|
Be aware that data is lost and cannot be recovered after running these commands.
|
|
:::
|
|
|
|
<Tabs>
|
|
<TabItem value="docker-compose" label="Docker Compose" default>
|
|
|
|
* Rebuild containers: This command destroys and recreates the containers. Data stored exclusively on the containers is lost, such as Langflow flows.
|
|
The `.env` file, `config` directory, `./openrag-documents` directory, `./opensearch-data` directory, and the `conversations.json` file are preserved.
|
|
|
|
```bash
|
|
docker compose up --build --force-recreate --remove-orphans
|
|
```
|
|
|
|
* Destroy and recreate containers with the option for additional data removal: These commands destroy the containers, and then recreate them.
|
|
This allows you to delete other OpenRAG data before recreating the containers.
|
|
|
|
1. Destroy the containers, volumes, and local images, and then remove (prune) any additional Docker objects:
|
|
|
|
```bash
|
|
docker compose down --volumes --remove-orphans --rmi local
|
|
docker system prune -f
|
|
```
|
|
|
|
2. Optional: Remove data that wasn't deleted by the previous commands:
|
|
|
|
* OpenRAG's `.env` file
|
|
* The contents of OpenRAG's `config` directory
|
|
* The contents of the `./openrag-documents` directory
|
|
* The contents of the `./opensearch-data` directory
|
|
* The `conversations.json` file
|
|
|
|
3. Recreate the containers:
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="Podman-compose" label="Podman Compose">
|
|
|
|
* Rebuild containers: This command destroys and recreates the containers. Data stored exclusively on the containers is lost, such as Langflow flows.
|
|
The `.env` file, `config` directory, `./openrag-documents` directory, `./opensearch-data` directory, and the `conversations.json` file are preserved.
|
|
|
|
```bash
|
|
podman-compose up --build --force-recreate --remove-orphans
|
|
```
|
|
|
|
* Destroy and recreate containers with the option for additional data removal: These commands destroy the containers, and then recreate them.
|
|
This allows you to delete other OpenRAG data before recreating the containers.
|
|
|
|
1. Destroy the containers, volumes, and local images, and then remove (prune) any additional Podman objects:
|
|
|
|
```bash
|
|
podman-compose down --volumes --remove-orphans --rmi local
|
|
podman system prune -f
|
|
```
|
|
|
|
2. Optional: Remove data that wasn't deleted by the previous commands:
|
|
|
|
* OpenRAG's `.env` file
|
|
* The contents of OpenRAG's `config` directory
|
|
* The contents of the `./openrag-documents` directory
|
|
* The contents of the `./opensearch-data` directory
|
|
* The `conversations.json` file
|
|
|
|
3. Recreate the containers:
|
|
|
|
```bash
|
|
podman-compose up -d
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="docker" label="Docker">
|
|
|
|
1. Stop all running containers:
|
|
|
|
```bash
|
|
docker stop $(docker ps -q)
|
|
```
|
|
|
|
2. Remove all containers, including stopped containers:
|
|
|
|
```bash
|
|
docker rm --force $(docker ps -aq)
|
|
```
|
|
|
|
3. Remove all images:
|
|
|
|
```bash
|
|
docker rmi --force $(docker images -q)
|
|
```
|
|
|
|
4. Remove all volumes:
|
|
|
|
```bash
|
|
docker volume prune --force
|
|
```
|
|
|
|
5. Remove all networks except the default network:
|
|
|
|
```bash
|
|
docker network prune --force
|
|
```
|
|
|
|
6. Clean up any leftover data:
|
|
|
|
```bash
|
|
docker system prune --all --force --volumes
|
|
```
|
|
|
|
7. Optional: Remove data that wasn't deleted by the previous commands:
|
|
|
|
* OpenRAG's `.env` file
|
|
* The contents of OpenRAG's `config` directory
|
|
* The contents of the `./openrag-documents` directory
|
|
* The contents of the `./opensearch-data` directory
|
|
* The `conversations.json` file
|
|
|
|
</TabItem>
|
|
<TabItem value="podman" label="Podman">
|
|
|
|
1. Stop all running containers:
|
|
|
|
```bash
|
|
podman stop --all
|
|
```
|
|
|
|
2. Remove all containers, including stopped containers:
|
|
|
|
```bash
|
|
podman rm --all --force
|
|
```
|
|
|
|
3. Remove all images:
|
|
|
|
```bash
|
|
podman rmi --all --force
|
|
```
|
|
|
|
4. Remove all volumes:
|
|
|
|
```bash
|
|
podman volume prune --force
|
|
```
|
|
|
|
5. Remove all networks except the default network:
|
|
|
|
```bash
|
|
podman network prune --force
|
|
```
|
|
|
|
6. Clean up any leftover data:
|
|
|
|
```bash
|
|
podman system prune --all --force --volumes
|
|
```
|
|
|
|
7. Optional: Remove data that wasn't deleted by the previous commands:
|
|
|
|
* OpenRAG's `.env` file
|
|
* The contents of OpenRAG's `config` directory
|
|
* The contents of the `./openrag-documents` directory
|
|
* The contents of the `./opensearch-data` directory
|
|
* The `conversations.json` file
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
After resetting your containers, you must repeat [application onboarding](#application-onboarding). |