Revamp README with TUI interface and dev guide
This commit is contained in:
Edwin Jose
parent
652ab2803f
commit
36e7031bf2
1 changed files with 72 additions and 66 deletions
138
README.md
138
README.md
|
|
@ -7,9 +7,10 @@ OpenRAG is a comprehensive Retrieval-Augmented Generation platform that enables
|
||||||
## 📋 Table of Contents
|
## 📋 Table of Contents
|
||||||
|
|
||||||
- [Quick Start](#quick-start)
|
- [Quick Start](#quick-start)
|
||||||
- [Development](#development)
|
- [TUI Interface](#tui-interface)
|
||||||
- [Configuration](#configuration)
|
- [Configuration](#configuration)
|
||||||
- [Docker Deployment](#docker-deployment)
|
- [Docker Deployment](#docker-deployment)
|
||||||
|
- [Development](#development)
|
||||||
- [Troubleshooting](#troubleshooting)
|
- [Troubleshooting](#troubleshooting)
|
||||||
|
|
||||||
## 🚀 Quick Start
|
## 🚀 Quick Start
|
||||||
|
|
@ -60,85 +61,72 @@ Access the services:
|
||||||
- **OpenSearch**: http://localhost:9200
|
- **OpenSearch**: http://localhost:9200
|
||||||
- **OpenSearch Dashboards**: http://localhost:5601
|
- **OpenSearch Dashboards**: http://localhost:5601
|
||||||
|
|
||||||
## 🛠️ Development
|
## 🖥️ TUI Interface
|
||||||
|
|
||||||
### Development Commands
|
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.
|
||||||
|
|
||||||
All development tasks are managed through the Makefile. Run `make help` to see all available commands.
|
|
||||||
|
|
||||||
#### Environment Management
|
### Launching the TUI
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Setup development environment
|
# Install dependencies first
|
||||||
make setup # Initial setup: creates .env, installs dependencies
|
uv sync
|
||||||
|
|
||||||
# Start development environments
|
# Launch the TUI
|
||||||
make dev # Full stack with GPU support
|
uv run openrag
|
||||||
make dev-cpu # Full stack with CPU only
|
|
||||||
make dev-local # Infrastructure only (for local development)
|
|
||||||
make infra # Alias for dev-local
|
|
||||||
|
|
||||||
# Container management
|
|
||||||
make stop # Stop all containers
|
|
||||||
make restart # Restart all containers
|
|
||||||
make clean # Stop and remove containers/volumes
|
|
||||||
make status # Show container status
|
|
||||||
make health # Check service health
|
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Local Development
|
### TUI Features
|
||||||
|
|
||||||
For faster development iteration, run infrastructure in Docker and backend/frontend locally:
|
The TUI provides several screens and capabilities:
|
||||||
|
|
||||||
```bash
|
#### Welcome Screen
|
||||||
# Terminal 1: Start infrastructure
|
- **Quick Setup Options**: Choose between basic setup (no authentication) or advanced setup (with OAuth)
|
||||||
make dev-local
|
- **Service Monitoring**: Check if containers are running and their status
|
||||||
|
- **Quick Actions**: Access diagnostics, logs, and configuration screens
|
||||||
|
|
||||||
# Terminal 2: Run backend locally
|
#### Configuration Screen
|
||||||
make backend
|
- **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
|
||||||
|
|
||||||
# Terminal 3: Run frontend locally
|
#### Service Monitor
|
||||||
make frontend
|
- **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
|
||||||
|
|
||||||
#### Dependency Management
|
#### 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
|
||||||
|
|
||||||
```bash
|
#### Diagnostics
|
||||||
make install # Install all dependencies
|
- **System Check**: Verify Docker/Podman installation and configuration
|
||||||
make install-be # Install backend dependencies (uv)
|
- **Environment Validation**: Check required environment variables
|
||||||
make install-fe # Install frontend dependencies (npm)
|
- **Network Testing**: Test connectivity between services
|
||||||
```
|
- **Performance Metrics**: System resource availability and recommendations
|
||||||
|
|
||||||
#### Building and Testing
|
### TUI Navigation
|
||||||
|
|
||||||
```bash
|
- **Arrow Keys**: Navigate between options and screens
|
||||||
# Build Docker images
|
- **Tab/Shift+Tab**: Move between form fields and buttons
|
||||||
make build # Build all images
|
- **Enter**: Select/activate options
|
||||||
make build-be # Build backend image only
|
- **Escape**: Go back to previous screen
|
||||||
make build-fe # Build frontend image only
|
- **Q**: Quit the application
|
||||||
|
- **Number Keys (1-4)**: Quick access to main screens from welcome
|
||||||
|
|
||||||
# Testing and quality
|
### Benefits of Using the TUI
|
||||||
make test # Run backend tests
|
|
||||||
make lint # Run linting checks
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Debugging
|
1. **Simplified Setup**: No need to manually edit configuration files
|
||||||
|
2. **Visual Feedback**: Clear status indicators and error messages
|
||||||
```bash
|
3. **Integrated Monitoring**: Everything in one interface
|
||||||
# View logs
|
4. **Cross-Platform**: Works on Linux, macOS, and Windows
|
||||||
make logs # All container logs
|
5. **No Browser Required**: Fully terminal-based interface
|
||||||
make logs-be # Backend logs only
|
|
||||||
make logs-fe # Frontend logs only
|
|
||||||
make logs-lf # Langflow logs only
|
|
||||||
make logs-os # OpenSearch logs only
|
|
||||||
|
|
||||||
|
|
||||||
#### Database Operations
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Reset OpenSearch indices
|
|
||||||
make db-reset # Delete and recreate indices
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
## ⚙️ Configuration
|
## ⚙️ Configuration
|
||||||
|
|
@ -239,8 +227,26 @@ podman machine start
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### Development Tips
|
## 🛠️ Development
|
||||||
|
|
||||||
- Use `make infra` + `make backend` + `make frontend` for faster development iteration
|
For developers wanting to contribute to OpenRAG or set up a development environment, please see our comprehensive development guide:
|
||||||
- Run `make help` to see all available commands
|
|
||||||
- Check `.env.example` for complete environment variable documentation
|
**[📚 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