diff --git a/README.md b/README.md index 021d8d3b..1b8025c4 100644 --- a/README.md +++ b/README.md @@ -3,15 +3,13 @@ [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/phact/openrag) 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. - -## 📋 Table of Contents - -- [Quick Start](#quick-start) -- [TUI Interface](#tui-interface) -- [Configuration](#configuration) -- [Docker Deployment](#docker-deployment) -- [Development](#development) -- [Troubleshooting](#troubleshooting) +
+ 🚀 Quick Start   |   + 💻 TUI Interface   |   + 🐳 Docker Deployment   |   + ⚙️ Development   |   + 🔧 Troubleshooting +
## 🚀 Quick Start @@ -43,7 +41,8 @@ LANGFLOW_CHAT_FLOW_ID=your_chat_flow_id LANGFLOW_INGEST_FLOW_ID=your_ingest_flow_id NUDGES_FLOW_ID=your_nudges_flow_id ``` - +ee extended configuration, including ingestion and optional variables: [docs/configuration.md](docs/ +configuration.md) ### 3. Start OpenRAG ```bash @@ -79,95 +78,10 @@ uv run openrag ### TUI Features -The TUI provides several screens and capabilities: - -#### Welcome Screen -- **Quick Setup Options**: Choose between basic setup (no authentication) or advanced setup (with OAuth) -- **Service Monitoring**: Check if containers are running and their status -- **Quick Actions**: Access diagnostics, logs, and configuration screens - -#### Configuration Screen -- **Environment Variables**: Easy-to-use forms for setting up required configuration -- **API Keys**: Secure input for OpenAI API keys with validation -- **OAuth Setup**: Configure Google and Microsoft authentication -- **Document Paths**: Set up document ingestion directories -- **Auto-Save**: Automatically generates and saves `.env` file - -#### Service Monitor -- **Container Status**: Real-time view of all OpenRAG services -- **Resource Usage**: Monitor CPU, memory, and network usage -- **Service Control**: Start, stop, and restart individual services -- **Health Checks**: Built-in health monitoring for all components - -#### Log Viewer -- **Real-time Logs**: Live streaming of container logs -- **Service Filtering**: View logs for specific services (backend, frontend, Langflow, OpenSearch) -- **Log Levels**: Filter by log levels (DEBUG, INFO, WARNING, ERROR) -- **Export Options**: Save logs to files for analysis - -#### Diagnostics -- **System Check**: Verify Docker/Podman installation and configuration -- **Environment Validation**: Check required environment variables -- **Network Testing**: Test connectivity between services -- **Performance Metrics**: System resource availability and recommendations - -### TUI Navigation - -- **Arrow Keys**: Navigate between options and screens -- **Tab/Shift+Tab**: Move between form fields and buttons -- **Enter**: Select/activate options -- **Escape**: Go back to previous screen -- **Q**: Quit the application -- **Number Keys (1-4)**: Quick access to main screens from welcome - -### Benefits of Using the TUI - -1. **Simplified Setup**: No need to manually edit configuration files -2. **Visual Feedback**: Clear status indicators and error messages -3. **Integrated Monitoring**: Everything in one interface -4. **Cross-Platform**: Works on Linux, macOS, and Windows -5. **No Browser Required**: Fully terminal-based interface +See the full TUI guide for features, navigation, and benefits: [docs/tui.md](docs/tui.md) -## ⚙️ Configuration -### Environment Variables - -OpenRAG uses environment variables for configuration. All variables should be set in your `.env` file. - -#### Required Variables - -| Variable | Description | -|----------|-------------| -| `OPENAI_API_KEY` | Your OpenAI API key | -| `OPENSEARCH_PASSWORD` | Password for OpenSearch admin user | -| `LANGFLOW_SUPERUSER` | Langflow admin username | -| `LANGFLOW_SUPERUSER_PASSWORD` | Langflow admin password | -| `LANGFLOW_CHAT_FLOW_ID` | ID of your Langflow chat flow | -| `LANGFLOW_INGEST_FLOW_ID` | ID of your Langflow ingestion flow | -| `NUDGES_FLOW_ID` | ID of your Langflow nudges/suggestions flow | - -#### Ingestion Configuration - -| Variable | Description | -|----------|-------------| -| `DISABLE_INGEST_WITH_LANGFLOW` | Disable Langflow ingestion pipeline (default: `false`) | - -- `false` or unset: Uses Langflow pipeline (upload → ingest → delete) -- `true`: Uses traditional OpenRAG processor for document ingestion - -#### Optional Variables - -| Variable | Description | -|----------|-------------| -| `LANGFLOW_PUBLIC_URL` | Public URL for Langflow (default: `http://localhost:7860`) | -| `GOOGLE_OAUTH_CLIENT_ID` / `GOOGLE_OAUTH_CLIENT_SECRET` | Google OAuth authentication | -| `MICROSOFT_GRAPH_OAUTH_CLIENT_ID` / `MICROSOFT_GRAPH_OAUTH_CLIENT_SECRET` | Microsoft OAuth | -| `WEBHOOK_BASE_URL` | Base URL for webhook endpoints | -| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | AWS integrations | -| `SESSION_SECRET` | Session management (default: auto-generated, change in production) | -| `LANGFLOW_KEY` | Explicit Langflow API key (auto-generated if not provided) | -| `LANGFLOW_SECRET_KEY` | Secret key for Langflow internal operations | ## 🐳 Docker Deployment @@ -187,23 +101,7 @@ For environments without GPU support: docker compose -f docker-compose-cpu.yml up -d ``` -### Force Rebuild - -If you need to reset state or rebuild everything: - -```bash -docker compose up --build --force-recreate --remove-orphans -``` - -### Service URLs - -After deployment, services are available at: - -- **Frontend**: http://localhost:3000 -- **Backend API**: http://localhost:8000 -- **Langflow**: http://localhost:7860 -- **OpenSearch**: http://localhost:9200 -- **OpenSearch Dashboards**: http://localhost:5601 +More deployment commands and tips: [docs/docker.md](docs/docker.md) ## 🔧 Troubleshooting @@ -220,10 +118,7 @@ podman machine start ### Common Issues -1. **OpenSearch fails to start**: Check that `OPENSEARCH_PASSWORD` is set and meets requirements -2. **Langflow connection issues**: Verify `LANGFLOW_SUPERUSER` credentials are correct -3. **Out of memory errors**: Increase Docker memory allocation or use CPU-only mode -4. **Port conflicts**: Ensure ports 3000, 7860, 8000, 9200, 5601 are available +See common issues and fixes: [docs/troubleshooting.md](docs/troubleshooting.md)