🧠 BrainStack - Local RAG System

BrainStack is a modular, scalable RAG (Retrieval-Augmented Generation) system built in Rust with HTMX. It can run entirely locally or in enterprise environments, with flexible LLM provider support and auto-detection of infrastructure services.

New User? Check out the User Guide for a beginner-friendly walkthrough!

✨ Features

Core Capabilities

• Flexible Source Management: Local files, S3/Minio, PostgreSQL, APIs
• Multiple LLM Providers: OpenAI, Claude, Grok, or Ollama (local)
• Vector Store Options: Qdrant, Milvus, or FAISS
• Docker-first: Complete infrastructure via docker-compose
• Auto-discovery: Automatically detects and uses available services

Modern UI

• Glassmorphism Design: Beautiful, modern interface with gradient effects
• Multi-language Support: English, French, Arabic, Hindi with RTL support
• Collapsible Sidebar: Maximize your workspace
• Unified Admin Panel: All settings in one place with internal tabs
• Smart Chat Management: Create, select, and delete conversations easily
• HTMX-powered: Lightweight, server-side rendered, no heavy JavaScript frameworks

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• (Optional) Rust 1.91.1+ for local development

Installation

Using Makefile (Recommended):

# One-command start
make start

Using Docker Compose directly:

# Start all services
docker-compose up -d

# Check logs
docker-compose logs -f brainstack

The application will be available at: http://localhost:3000

First-Time Setup

1. Access the Application

   • Navigate to http://localhost:3000
   • You'll see the admin dashboard

2. Configure LLM Provider (Admin > LLM Providers)

   • Click the Admin button in the sidebar
   • Select "LLM Providers" tab
   • Add your OpenAI API key, Claude API key, or configure Ollama
   • Test the connection

3. Add Data Sources (Admin > Sources)

   • Select "Sources" tab in Admin
   • Click "Add Source"
   • Configure local paths, S3 buckets, or database connections
   • Sources will be indexed automatically

4. Customize Prompts (Admin > Prompts) - Optional

   • Select "Prompts" tab
   • Create custom system prompts for different use cases
   • Apply prompts in your chat conversations

5. Start Chatting

   • Click the logo or use the chat menu
   • Select a prompt template (optional)
   • Ask questions and get AI-powered answers from your data

Using the Interface

Navigation:

• Collapsible Sidebar: Click the ☰ button to collapse/expand the menu
• Language Selector: Top-right dropdown (English, Français, العربية, हिन्दी)
• Admin Settings: Click "Admin" button to access all configuration in one place with tabs
• Chat Management:
  • ✏️ button: Start a new chat
  • 🗑️ button: Enter delete mode to remove chats
  • Select individual chats or use "Select All"

Common Commands:

make start      # Start BrainStack
make stop       # Stop all services
make logs       # View logs
make health     # Check service status
make rebuild    # Rebuild after template changes
make help       # See all available commands

📦 Services

The docker-compose setup includes:

• BrainStack App (Port 3000) - Main application
• PostgreSQL (Port 5432) - Metadata storage
• Redis (Port 6379) - Query caching
• Qdrant (Port 6333) - Vector database
• Minio (Port 9000/9001) - S3-compatible object storage
• Ollama (Optional, Port 11434) - Local LLM inference

Minio Setup

Access Minio console at http://localhost:9001

• Username: minioadmin
• Password: minioadmin

Create a bucket and configure it as a source in BrainStack.

🛠️ Development

Local Development (without Docker)

Using Makefile:

# Start infrastructure services only
make infra

# Run the app locally
make run

# Development mode with auto-reload (requires cargo-watch)
make dev

Manual setup:

# Install dependencies
cargo build

# Create config directories
mkdir -p config data assets

# Copy example configs
cp config/config.example.json config/config.json
cp config/sources.example.json config/sources.json

# Run the application
cargo run

Making Template Changes

When modifying templates (in templates/ directory), you need to rebuild the Docker image because Askama compiles templates into the binary at build time:

make rebuild
# or
docker-compose up -d --build brainstack

Project Structure

brainstack/
├── src/
│   ├── main.rs              # Application entry point
│   ├── config.rs            # Configuration management
│   ├── models.rs            # Data models
│   ├── state.rs             # Application state
│   ├── routes/              # HTTP route handlers
│   │   ├── admin.rs
│   │   ├── sources.rs
│   │   ├── prompts.rs
│   │   ├── providers.rs
│   │   ├── chat.rs
│   │   └── api.rs
│   └── services/            # Business logic
│       ├── storage.rs
│       ├── rag.rs
│       └── llm.rs
├── templates/               # HTMX templates
│   ├── base.html
│   ├── admin/
│   └── chat/
├── config/                  # Configuration files
├── data/                    # SQLite database (if used)
├── docker-compose.yml       # Infrastructure setup
└── Dockerfile              # App container

🔧 Configuration

Environment Variables

• DATABASE_URL: Database connection string (default: sqlite://data/brainstack.db)
• RUST_LOG: Logging level (default: info)

Sources Configuration

Sources can be added via UI or by editing config/sources.json:

{
  "sources": [
    {
      "id": "src_001",
      "type": "local_path",
      "label": "Documents",
      "path": "/data/docs",
      "icon": "https://cdn-icons-png.flaticon.com/512/716/716784.png",
      "indexing": {
        "recursive": true,
        "file_types": ["pdf", "md", "txt"]
      },
      "enabled": true
    }
  ]
}

Supported Source Types

• local_path: Local file system
• postgres: PostgreSQL database
• s3: S3 or Minio bucket
• api: REST API endpoint

🎯 API Usage

BrainStack provides a JSON API for programmatic access:

curl -X POST http://localhost:3000/api/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is in my documents?",
    "top_k": 5
  }'

Response:

{
  "answer": "Based on your documents...",
  "sources": ["document1.pdf", "document2.md"],
  "model_used": "openai"
}

🔧 Troubleshooting

Services show "Not configured"

• Ensure all environment variables are set in docker-compose.yml
• Check infrastructure status: Admin > Infrastructure > Check Services
• Verify services are running: make status
• Check service health: make health

Template changes not appearing

• Askama compiles templates into the binary at build time
• After template changes, rebuild: make rebuild

Application not starting

# Check logs
make logs-app

# Verify all services are running
make status

# Check service health
make health

# Restart services
make restart

Port conflicts

If ports 3000, 5432, 6379, 6333, or 9000-9001 are already in use:

• Stop conflicting services
• Or modify port mappings in docker-compose.yml

Database connection errors

• Ensure PostgreSQL is running: docker-compose ps postgres
• Check DATABASE_URL in config/config.json
• Verify network connectivity between containers

🚢 Production Deployment

Using Docker Compose

1. Update docker-compose.yml with production settings
2. Set strong passwords for PostgreSQL and Minio
3. Configure SSL/TLS termination (nginx/traefik)
4. Set up backups for volumes

Environment-specific Configuration

Create a .env file:

DATABASE_URL=postgres://user:pass@postgres:5432/brainstack
OPENAI_API_KEY=sk-...
RUST_LOG=info

📊 Monitoring

Check service health:

• Admin > Infrastructure > Check Services
• Docker: docker-compose ps
• Logs: docker-compose logs -f

🔐 Security Notes

• Change default passwords in production
• Use HTTPS in production
• Secure API endpoints with authentication
• Limit file upload sizes
• Sanitize user inputs

🗺️ Roadmap

• Full vector search implementation
• Real LLM provider integrations
• Multi-format document parsing (PDF, audio, images)
• Database persistence layer
• Multi-tenancy support
• RBAC and audit logs
• Webhook integrations
• Delta indexing

📝 License

MIT

🤝 Contributing

Contributions welcome! Please open an issue or PR.

📧 Support

For issues and questions, please open a GitHub issue.

---

Built with ❤️ using Rust, Axum, and HTMX