Deployment & Upgrades
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The RAGAPPv3 platform is a self-hosted Retrieval-Augmented Generation (RAG) knowledge base application designed for technical document ingestion and chat-based retrieval. The deployment architecture relies on a decoupled stack consisting of a FastAPI backend, a React-based frontend, and specialized vector (LanceDB) and relational (SQLite) storage layers. Retrieval is augmented by local LLM services (Ollama) or external providers. Sources: INSTALLATION.md:3-15, CONTRIBUTING.md:12-18
The deployment lifecycle encompasses native environment setup, containerized orchestration via Docker, and an idempotent database migration system that ensures schema consistency during upgrades. The system supports multi-platform deployment on Windows 11, macOS, and Linux, emphasizing local inference for data privacy. Sources: INSTALLATION.md:20-100
Deployment Architecture
The application is distributed as a series of integrated services. In a standard production-like deployment, these services are orchestrated to communicate over a common network, with persistent storage volumes mounted for databases and document uploads.
The diagram above illustrates the high-level service architecture and data flow between the user interface and the backend processing layers. Sources: INSTALLATION.md:205-240, qa-report.md:540-560
Core Components
| Component | Technology | Role |
|---|---|---|
| Backend | Python 3.11, FastAPI | API routing, RAG logic, and vault management. |
| Frontend | React, TypeScript, Vite | User interface and chat interaction. |
| Database | SQLite (WAL mode) | Storage for metadata, users, sessions, and wiki claims. |
| Vector Store | LanceDB | Storage for document chunk embeddings. |
| LLM Inference | Ollama | Local chat model execution. |
| Embedding | Harrier TEI | High-performance embedding generation. |
Sources: INSTALLATION.md:5-15, CONTRIBUTING.md:12-15, backend/app/models/database.py:1010-1030
Installation Methods
Native Installation
Native deployment requires Python 3.11 and Node.js 18+. The process involves setting up a virtual environment, installing dependencies from requirements.txt, and building the frontend assets. Users must also configure environment variables in a .env file, specifically setting JWT_SECRET_KEY and ADMIN_SECRET_TOKEN to secure the instance. Sources: INSTALLATION.md:120-195, CONTRIBUTING.md:40-60
Docker Orchestration
Containerized deployment is the recommended method for production-like stability. The docker-compose.yml file defines three primary services: backend, frontend, and ollama. Persistent storage is managed via volumes for SQLite databases (/app/data) and document uploads (/app/uploads). Sources: INSTALLATION.md:200-230
Deployment Security Note: Current QA reports indicate that the default Dockerfile may run as a root user, which is identified as a critical security risk during document parsing. It is recommended to implement a non-root USER directive before production use. Sources: qa-report.md:44-53
Configuration Management
Deployment behavior is controlled via environment variables. Key configurations include model selection and service URLs.
| Variable | Default / Example | Description |
|---|---|---|
OLLAMA_CHAT_URL | http://localhost:11434 | URL for the Ollama chat service. |
EMBEDDING_MODEL | microsoft/harrier-oss-v1-0.6b | Model used for vector embeddings. |
CHAT_MODEL | gemma-4-26b-a4b-it-apex | Model used for generating chat responses. |
EMBEDDING_BATCH_SIZE | 32 | Number of chunks processed per embedding request. |
WIKI_ENABLED | true | Master switch for the Wiki subsystem. |
Sources: INSTALLATION.md:300-340, backend/app/api/routes/wiki.py:30-40
Database Migrations & Upgrades
The application uses an idempotent migration system defined in backend/app/models/database.py. This system allows the database to be upgraded safely across versions without data loss by checking for existing columns and tables before applying changes. Sources: backend/app/models/database.py:465-480
Migration Lifecycle
When the application starts, it executes run_migrations(), which performs the following sequence:
- Initialization: Calls
init_db()to create the base schema usingPRAGMA journal_mode=WALfor high-concurrency performance. - Incremental Updates: Executes specialized migration functions (e.g.,
migrate_add_vaults,migrate_add_wiki_tables) that check table info viaPRAGMA table_info. - FTS Synchronization: Rebuilds Virtual Tables for Full-Text Search (FTS5) to ensure search indexes match the current document and wiki content.
Critical Migration Functions
| Function | Purpose |
|---|---|
migrate_add_vaults | Adds multi-tenant vault support to legacy flat-file databases. |
migrate_vault_paths | Renames filesystem directories from sanitized names to numeric IDs. |
migrate_add_wiki_tables | Creates schemas for pages, claims, entities, and compile jobs. |
migrate_add_files_content_fts | Adds FTS5 index over parsed_text for body-text search. |
migrate_add_curator_claim_support | Recreates tables to support broadened status constraints for LLM curators. |
Sources: backend/app/models/database.py:553-600, backend/app/models/database.py:1260-1280, specs/kms-content-search-rag/SPEC.md:85-110
Upgrade Procedures
Upgrading an existing installation involves pulling the latest code and restarting the services. Because migrations are idempotent and run on startup, the primary concern is ensuring data persistence.
- Backup: It is recommended to backup the SQLite
.dbfile before major version upgrades. Sources: INSTALLATION.md:465-470 - Pull Updates: Fetch the latest source or pull updated Docker images.
- Dependency Refresh: In native installs, run
pip install -r requirements.txtandnpm install. Sources: CONTRIBUTING.md:105-115 - Restart: Restart the backend. The
run_migrations()function will automatically detect the current schema version and apply necessaryALTER TABLEorCREATE TABLEstatements. Sources: backend/app/models/database.py:485-500
Conclusion
The deployment and upgrade framework of RAGAPPv3 is built for resilience and ease of maintenance. By combining containerized orchestration with an idempotent migration engine, the platform simplifies the transition between versions while maintaining the integrity of retrieved knowledge across relational and vector storage layers. Efficient upgrades are further supported by built-in FTS rebuilds and vault path sanitization, ensuring a stable environment for production RAG workloads. Sources: INSTALLATION.md:480-495, backend/app/models/database.py:530-550