Merge pull request #229 from langflow-ai/docs-readme
docs: update readme
This commit is contained in:
Nate McCall
GitHub
commit
38d94ba482
2 changed files with 125 additions and 131 deletions
|
|
@ -11,20 +11,48 @@ Thank you for your interest in contributing to OpenRAG! This guide will help you
|
||||||
- Python 3.13+ with uv package manager
|
- Python 3.13+ with uv package manager
|
||||||
- Node.js 18+ and npm
|
- Node.js 18+ and npm
|
||||||
|
|
||||||
### Environment Setup
|
### Set up OpenRAG for development
|
||||||
|
|
||||||
|
1. Set up your development environment.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Clone the repository
|
# Clone and setup environment
|
||||||
git clone <repository-url>
|
git clone https://github.com/langflow-ai/openrag.git
|
||||||
cd openrag
|
cd openrag
|
||||||
|
|
||||||
# Setup development environment
|
|
||||||
make setup # Creates .env and installs dependencies
|
make setup # Creates .env and installs dependencies
|
||||||
```
|
```
|
||||||
|
|
||||||
### Configuration
|
2. Configure the `.env` file with your API keys and credentials.
|
||||||
|
|
||||||
Edit `.env` with your API keys and credentials. See the main README for required environment variables.
|
```bash
|
||||||
|
# Required
|
||||||
|
OPENAI_API_KEY=your_openai_api_key
|
||||||
|
OPENSEARCH_PASSWORD=your_secure_password
|
||||||
|
LANGFLOW_SUPERUSER=admin
|
||||||
|
LANGFLOW_SUPERUSER_PASSWORD=your_secure_password
|
||||||
|
LANGFLOW_CHAT_FLOW_ID=your_chat_flow_id
|
||||||
|
LANGFLOW_INGEST_FLOW_ID=your_ingest_flow_id
|
||||||
|
NUDGES_FLOW_ID=your_nudges_flow_id
|
||||||
|
```
|
||||||
|
|
||||||
|
For extended configuration, including ingestion and optional variables, see [docs/reference/configuration.mdx](docs/docs/reference/configuration.mdx).
|
||||||
|
|
||||||
|
3. Start OpenRAG.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Full stack with GPU support
|
||||||
|
make dev
|
||||||
|
|
||||||
|
# Or CPU only
|
||||||
|
make dev-cpu
|
||||||
|
```
|
||||||
|
|
||||||
|
Access the services:
|
||||||
|
- **Frontend**: http://localhost:3000
|
||||||
|
- **Backend API**: http://localhost:8000
|
||||||
|
- **Langflow**: http://localhost:7860
|
||||||
|
- **OpenSearch**: http://localhost:9200
|
||||||
|
- **OpenSearch Dashboards**: http://localhost:5601
|
||||||
|
|
||||||
## 🔧 Development Commands
|
## 🔧 Development Commands
|
||||||
|
|
||||||
|
|
|
||||||
214
README.md
214
README.md
|
|
@ -2,20 +2,6 @@
|
||||||
|
|
||||||
# OpenRAG
|
# OpenRAG
|
||||||
|
|
||||||
</div>
|
|
||||||
<div align="center">
|
|
||||||
<a href="#quick-start" style="color: #0366d6;">🚀 Quick Start</a> |
|
|
||||||
<a href="#tui-interface" style="color: #0366d6;">💻 TUI Interface</a> |
|
|
||||||
<a href="#docker-deployment" style="color: #0366d6;">🐳 Docker Deployment</a> |
|
|
||||||
<a href="#development" style="color: #0366d6;">⚙️ Development</a> |
|
|
||||||
<a href="#troubleshooting" style="color: #0366d6;">🔧 Troubleshooting</a>
|
|
||||||
</div>
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
OpenRAG is a comprehensive Retrieval-Augmented Generation platform that enables intelligent document search and AI-powered conversations. Users can upload, process, and query documents through a chat interface backed by large language models and semantic search capabilities. The system utilizes Langflow for document ingestion, retrieval workflows, and intelligent nudges, providing a seamless RAG experience. Built with Starlette, Next.js, OpenSearch, and Langflow integration. [](https://deepwiki.com/phact/openrag)
|
|
||||||
|
|
||||||
|
|
||||||
<div align="center">
|
<div align="center">
|
||||||
<a href="https://github.com/langflow-ai/langflow"><img src="https://img.shields.io/badge/Langflow-1C1C1E?style=flat&logo=langflow" alt="Langflow"></a>
|
<a href="https://github.com/langflow-ai/langflow"><img src="https://img.shields.io/badge/Langflow-1C1C1E?style=flat&logo=langflow" alt="Langflow"></a>
|
||||||
|
|
||||||
|
|
@ -24,144 +10,124 @@ OpenRAG is a comprehensive Retrieval-Augmented Generation platform that enables
|
||||||
<a href="https://github.com/encode/starlette"><img src="https://img.shields.io/badge/Starlette-009639?style=flat&logo=fastapi&logoColor=white" alt="Starlette"></a>
|
<a href="https://github.com/encode/starlette"><img src="https://img.shields.io/badge/Starlette-009639?style=flat&logo=fastapi&logoColor=white" alt="Starlette"></a>
|
||||||
|
|
||||||
<a href="https://github.com/vercel/next.js"><img src="https://img.shields.io/badge/Next.js-000000?style=flat&logo=next.js&logoColor=white" alt="Next.js"></a>
|
<a href="https://github.com/vercel/next.js"><img src="https://img.shields.io/badge/Next.js-000000?style=flat&logo=next.js&logoColor=white" alt="Next.js"></a>
|
||||||
|
|
||||||
|
<a href="https://deepwiki.com/phact/openrag"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
|
OpenRAG is a comprehensive Retrieval-Augmented Generation platform that enables intelligent document search and AI-powered conversations. Users can upload, process, and query documents through a chat interface backed by large language models and semantic search capabilities. The system utilizes Langflow for document ingestion, retrieval workflows, and intelligent nudges, providing a seamless RAG experience. Built with Starlette, Next.js, OpenSearch, and Langflow integration.
|
||||||
|
|
||||||
|
</div>
|
||||||
|
<div align="center">
|
||||||
|
<a href="#quickstart" style="color: #0366d6;">Quickstart</a> |
|
||||||
|
<a href="#tui-interface" style="color: #0366d6;">TUI Interface</a> |
|
||||||
|
<a href="#docker-deployment" style="color: #0366d6;">Docker Deployment</a> |
|
||||||
|
<a href="#development" style="color: #0366d6;">Development</a> |
|
||||||
|
<a href="#troubleshooting" style="color: #0366d6;">Troubleshooting</a>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
## Quickstart
|
||||||
|
|
||||||
|
Use the OpenRAG Terminal User Interface (TUI) to manage your OpenRAG installation without complex command-line operations.
|
||||||
|
|
||||||
|
To launch OpenRAG with the TUI, do the following:
|
||||||
|
|
||||||
## 🚀 Quick Start
|
1. Clone the OpenRAG repository.
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/langflow-ai/openrag.git
|
||||||
|
cd openrag
|
||||||
|
```
|
||||||
|
|
||||||
### Prerequisites
|
2. To start the TUI, from the repository root, run:
|
||||||
|
```bash
|
||||||
|
# Install dependencies first
|
||||||
|
uv sync
|
||||||
|
|
||||||
|
# Launch the TUI
|
||||||
|
uv run openrag
|
||||||
|
```
|
||||||
|
|
||||||
- Docker or Podman with Compose installed
|
The TUI opens and guides you through OpenRAG setup.
|
||||||
- Make (for development commands)
|
|
||||||
|
|
||||||
### 1. Environment Setup
|
For the full TUI guide, see [TUI](docs/docs/get-started/tui.mdx).
|
||||||
|
|
||||||
```bash
|
## Docker Deployment
|
||||||
# Clone and setup environment
|
|
||||||
git clone https://github.com/langflow-ai/openrag.git
|
|
||||||
cd openrag
|
|
||||||
make setup # Creates .env and installs dependencies
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Configure Environment
|
If you prefer to use Docker to run OpenRAG, the repository includes two Docker Compose `.yml` files.
|
||||||
|
They deploy the same applications and containers, but to different environments.
|
||||||
|
|
||||||
Edit `.env` with your API keys and credentials:
|
- [`docker-compose.yml`](https://github.com/langflow-ai/openrag/blob/main/docker-compose.yml) is an OpenRAG deployment for environments with GPU support. GPU support requires an NVIDIA GPU with CUDA support and compatible NVIDIA drivers installed on the OpenRAG host machine.
|
||||||
|
|
||||||
```bash
|
- [`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 GPU support. Use this Docker compose file for environments where GPU drivers aren't available.
|
||||||
# Required
|
|
||||||
OPENAI_API_KEY=your_openai_api_key
|
|
||||||
OPENSEARCH_PASSWORD=your_secure_password
|
|
||||||
LANGFLOW_SUPERUSER=admin
|
|
||||||
LANGFLOW_SUPERUSER_PASSWORD=your_secure_password
|
|
||||||
LANGFLOW_CHAT_FLOW_ID=your_chat_flow_id
|
|
||||||
LANGFLOW_INGEST_FLOW_ID=your_ingest_flow_id
|
|
||||||
NUDGES_FLOW_ID=your_nudges_flow_id
|
|
||||||
```
|
|
||||||
See extended configuration, including ingestion and optional variables: [docs/reference/configuration.md](docs/docs/reference/configuration.md)
|
|
||||||
### 3. Start OpenRAG
|
|
||||||
|
|
||||||
```bash
|
Both Docker deployments depend on `docling serve` to be running on port `5001` on the host machine. This enables [Mac MLX](https://opensource.apple.com/projects/mlx/) support for document processing. Installing OpenRAG with the TUI starts `docling serve` automatically, but for a Docker deployment you must manually start the `docling serve` process.
|
||||||
# Full stack with GPU support
|
|
||||||
make dev
|
|
||||||
|
|
||||||
# Or CPU only
|
To deploy OpenRAG with Docker:
|
||||||
make dev-cpu
|
|
||||||
```
|
|
||||||
|
|
||||||
Access the services:
|
1. Clone the OpenRAG repository.
|
||||||
- **Frontend**: http://localhost:3000
|
```bash
|
||||||
- **Backend API**: http://localhost:8000
|
git clone https://github.com/langflow-ai/openrag.git
|
||||||
- **Langflow**: http://localhost:7860
|
cd openrag
|
||||||
- **OpenSearch**: http://localhost:9200
|
```
|
||||||
- **OpenSearch Dashboards**: http://localhost:5601
|
|
||||||
|
|
||||||
## 🖥️ TUI Interface
|
2. Install dependencies.
|
||||||
|
```bash
|
||||||
|
uv sync
|
||||||
|
```
|
||||||
|
|
||||||
OpenRAG includes a powerful Terminal User Interface (TUI) for easy setup, configuration, and monitoring. The TUI provides a user-friendly way to manage your OpenRAG installation without complex command-line operations.
|
3. Start `docling serve` on the host machine.
|
||||||
|
```bash
|
||||||
|
uv run python scripts/docling_ctl.py start --port 5001
|
||||||
|
```
|
||||||
|
|
||||||
|
4. Confirm `docling serve` is running.
|
||||||
|
```
|
||||||
|
uv run python scripts/docling_ctl.py status
|
||||||
|
```
|
||||||
|
|
||||||
|
Successful result:
|
||||||
|
```bash
|
||||||
|
Status: running
|
||||||
|
Endpoint: http://127.0.0.1:5001
|
||||||
|
Docs: http://127.0.0.1:5001/docs
|
||||||
|
PID: 27746
|
||||||
|
```
|
||||||
|
|
||||||
### Launching the TUI
|
5. Build and start all services.
|
||||||
|
|
||||||
```bash
|
For the GPU-accelerated deployment, run:
|
||||||
# Install dependencies first
|
```bash
|
||||||
uv sync
|
docker compose build
|
||||||
|
docker compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
# Launch the TUI
|
For environments without GPU support, run:
|
||||||
uv run openrag
|
```bash
|
||||||
```
|
docker compose -f docker-compose-cpu.yml up -d
|
||||||
|
```
|
||||||
|
|
||||||
### TUI Features
|
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. |
|
||||||
|
|
||||||
See the full TUI guide for features, navigation, and benefits: [docs/get-started/tui.mdx](docs/docs/get-started/tui.mdx)
|
6. Access the OpenRAG application at `http://localhost:3000` and continue with the [Quickstart](docs/docs/get-started/quickstart.mdx).
|
||||||
|
|
||||||
|
To stop `docling serve`, run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
uv run python scripts/docling_ctl.py stop
|
||||||
|
```
|
||||||
|
|
||||||
|
For more information, see [Deploy with Docker](docs/docs/get-started/docker.mdx).
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
## 🐳 Docker Deployment
|
For common issues and fixes, see [Troubleshoot](docs/docs/support/troubleshoot.mdx).
|
||||||
|
|
||||||
### Standard Deployment
|
## Development
|
||||||
|
|
||||||
```bash
|
For developers wanting to contribute to OpenRAG or set up a development environment, see [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||||
# Build and start all services
|
|
||||||
docker compose build
|
|
||||||
docker compose up -d
|
|
||||||
```
|
|
||||||
|
|
||||||
### CPU-Only Deployment
|
|
||||||
|
|
||||||
For environments without GPU support:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker compose -f docker-compose-cpu.yml up -d
|
|
||||||
```
|
|
||||||
|
|
||||||
More deployment commands and tips: [docs/get-started/docker.mdx](docs/docs/get-started/docker.mdx)
|
|
||||||
|
|
||||||
## 🔧 Troubleshooting
|
|
||||||
|
|
||||||
### Podman on macOS
|
|
||||||
|
|
||||||
If using Podman on macOS, you may need to increase VM memory:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
podman machine stop
|
|
||||||
podman machine rm
|
|
||||||
podman machine init --memory 8192 # 8 GB example
|
|
||||||
podman machine start
|
|
||||||
```
|
|
||||||
|
|
||||||
### Common Issues
|
|
||||||
|
|
||||||
See common issues and fixes: [docs/support/troubleshoot.mdx](docs/docs/reference/troubleshoot.mdx)
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## 🛠️ Development
|
|
||||||
|
|
||||||
For developers wanting to contribute to OpenRAG or set up a development environment, please see our comprehensive development guide:
|
|
||||||
|
|
||||||
**[📚 See CONTRIBUTING.md for detailed development instructions](CONTRIBUTING.md)**
|
|
||||||
|
|
||||||
The contributing guide includes:
|
|
||||||
- Complete development environment setup
|
|
||||||
- Local development workflows
|
|
||||||
- Testing and debugging procedures
|
|
||||||
- Code style guidelines
|
|
||||||
- Architecture overview
|
|
||||||
- Pull request guidelines
|
|
||||||
|
|
||||||
### Quick Development Commands
|
|
||||||
|
|
||||||
```bash
|
|
||||||
make help # See all available commands
|
|
||||||
make setup # Initial development setup
|
|
||||||
make infra # Start infrastructure services
|
|
||||||
make backend # Run backend locally
|
|
||||||
make frontend # Run frontend locally
|
|
||||||
```
|
|
||||||
Loading…
Add table
Reference in a new issue