🧠 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/brainstackOPENAI_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