Introduction & Setup Guide
Relevant source files
The following files were used as context for generating this wiki page:
KnowledgeVault (RAGAPPv3) is a self-hosted web service designed for ingesting large volumes of technical documents and interacting with them via natural language chat using Retrieval-Augmented Generation (RAG). The system is built to be entirely self-contained, supporting local LLM inference and vector storage to ensure data privacy and performance on local infrastructure.
The application utilizes a modern tech stack comprising a FastAPI backend, a React-based frontend, and specialized databases for vector and metadata storage. It supports various document formats, including PDF, DOCX, CSV, and code files, while providing advanced features like semantic chunking, memory systems, and knowledge management (KMS).
Sources: README.md:1-12, INSTALLATION.md:3-12
System Architecture
The KnowledgeVault architecture follows a decoupled client-server model where the frontend interacts with a RESTful API. The backend orchestrates data flow between document processors, vector stores, and external or local LLM services.
The diagram illustrates the high-level flow from user interaction to backend processing and data storage.
Sources: README.md:105-135, INSTALLATION.md:14-25
Core Components
| Component | Technology | Description |
|---|---|---|
| Frontend | React 18, TypeScript, Vite | Responsive UI with three-zone chat workspace. |
| Backend | Python 3.11, FastAPI | Handles RAG orchestration, API routes, and business logic. |
| Vector DB | LanceDB (embedded) | Stores document embeddings for semantic similarity search. |
| Metadata DB | SQLite (FTS5) | Stores user data, chat sessions, and memory with full-text search. |
| Embeddings | Harrier TEI | Local dense embedding generation (1024-dim). |
| LLM | Ollama | Local LLM inference for chat and reasoning. |
| Sources: README.md:137-147, CONTRIBUTING.md:13-17 |
Prerequisites & Requirements
Before installation, ensure the following hardware and software requirements are met:
Hardware Requirements
- RAM: Minimum 8GB (16GB+ recommended).
- GPU: Recommended for Ollama/LLM inference speed, though CPU-only is supported.
Sources: README.md:154-156
Software Prerequisites
- Python: 3.11 (CI specifically pins this version; newer versions like 3.14 may cause event loop issues in tests).
- Node.js: ≥ 20.19.0 (defined in
frontend/package.json). - Ollama: Required for local LLM inference.
- Docker/Docker Compose: Required for containerized deployment.
Sources: CONTRIBUTING.md:21-25, INSTALLATION.md:30-45, CLAUDE.md:100-104
Installation Methods
Native Installation (Development)
Native installation is recommended for contributors and development environments.
- Clone the Repository:
git clone https://github.com/zaxbysauce/ragappv3.git cd ragappv3 - Backend Setup:
cd backend python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt pip install -r requirements-dev.txt - Frontend Setup:
cd ../frontend npm ci npm run dev - Database Initialization:
cd ../backend python -c "from app.models.database import init_db; init_db()"
Sources: CONTRIBUTING.md:30-45, INSTALLATION.md:100-145
Docker Installation (Production)
Docker Compose provides a streamlined way to deploy the entire stack, including the embedding service and Ollama.
The sequence diagram shows the container orchestration flow during startup.
- Prepare Environment: Copy
.env.exampleto.envand configureJWT_SECRET_KEYandADMIN_SECRET_TOKEN. - Launch Containers:
docker compose up -d - Pull Models:
docker compose exec ollama ollama pull qwen2.5:32b
Sources: README.md:168-185, INSTALLATION.md:160-245, docker-compose.yml:1-85
Configuration
KnowledgeVault relies on environment variables for service discovery and security.
Key Environment Variables
| Variable | Default | Description |
|---|---|---|
JWT_SECRET_KEY | (Required) | Secret for JWT signing. Generate with secrets.token_urlsafe(48). |
ADMIN_SECRET_TOKEN | (Required) | Token for initial admin setup and API access. |
OLLAMA_CHAT_URL | http://host.docker.internal:11434 | URL for the chat LLM service. |
OLLAMA_EMBEDDING_URL | http://harrier-embed:8080/v1/embeddings | URL for the TEI embedding service. |
CHAT_MODEL | gemma-4-26b-a4b-it-apex | The primary LLM model for thinking/chat. |
SQLITE_PATH | ./ragapp.db | Path to the metadata database file. |
EMBEDDING_BATCH_SIZE | 32 | Number of documents to embed in one request (Range: 1-128). |
| Sources: README.md:195-230, INSTALLATION.md:255-290, CONTRIBUTING.md:46-52 |
Initial Setup & Verification
After starting the services, a Setup Wizard is triggered upon the first visit to the web interface.
- Access Web UI: Navigate to
http://localhost:9090(orhttp://localhost:3000in dev). - Setup Account: Create the initial superadmin account via the wizard.
- Health Check: Verify the backend is functional via
curl http://localhost:9090/api/health.
Troubleshooting Connection Issues
- Ollama Refused: Ensure Ollama is running on the host and
OLLAMA_CHAT_URLis correctly pointed at the bridge IP orhost.docker.internal. - Database Locked: Common in SQLite when multiple Python processes attempt writes; ensure only one instance of the backend is running.
- CSRF Errors: Ensure the
X-CSRF-Tokenheader is present in mutating requests. The frontend automatically manages this via interceptors.
Sources: README.md:188-192, INSTALLATION.md:330-385, frontend/src/lib/api.ts:50-85
Summary
The "Introduction & Setup Guide" establishes KnowledgeVault as a robust, local RAG solution. By adhering to the pinned Python 3.11 environment and ensuring correct configuration of the Ollama and Harrier TEI service URLs, developers can deploy a secure knowledge base capable of processing diverse technical documentation. Following the initial setup wizard, users can immediately begin vault creation and document ingestion.
Sources: README.md:5-15, INSTALLATION.md:435-455