Deployment

I3K RAG Enterprise viene tipicamente installato con uno script one-command su un singolo host Linux. Per esigenze più grandi o vincolate, sono supportate anche topologie multi-server e air-gapped. In tutte le topologie girano gli stessi componenti — backend FastAPI, Qdrant, Ollama — cambia soltanto il modo in cui vengono cablati tra loro.

Topologie

Single-host (raccomandato per la maggior parte dei casi)

Tutti i componenti — backend FastAPI, frontend React + Vite, Qdrant, Ollama, SQLite per gli utenti, Apache Tika e Tesseract — girano sullo stesso server. L'installazione richiede un singolo comando e circa un'ora, in gran parte spesa per scaricare i modelli Qwen3:14b-q4_K_M e Mistral 7B Q4 e l'embedding BAAI/bge-m3 (29 lingue).

Adatto a team fino a qualche centinaio di utenti e dataset nell'ordine delle decine di migliaia di documenti. Lo stack è production-ready oltre i 10.000 documenti su hardware commodity.

Air-gapped

Per reti isolate senza connettività in uscita — tipico di Difesa, sanità e infrastrutture critiche. Lo script di installazione supporta l'installazione offline da pacchetti pre-scaricati e bundle di modelli. Si trasferisce il bundle tramite il canale approvato, si lancia l'installer e il sistema sale senza mai chiamare verso l'esterno.

Multi-server (avanzato)

Per carichi più grandi, Qdrant e Ollama possono essere spostati su nodi GPU dedicati, separati dal backend FastAPI. La configurazione è manuale e si applica dopo l'installazione standard: si punta il backend agli endpoint remoti di Qdrant e Ollama e si riavvia il servizio API.

Requisiti hardware

Il setup CPU-only è supportato ed è utile in valutazione, ma aspettati latenze sensibilmente più alte in generazione. Per workload di produzione pianifica almeno una GPU CUDA con 12 GB di VRAM.

Backup & restore

Il backup è integrato e si appoggia a rclone, quindi tutti gli oltre 70 provider supportati da rclone sono disponibili out of the box.

• Object storage: S3, MinIO, Backblaze B2, Wasabi ed endpoint S3-compatibili.
• Cloud consumer: Google Drive, OneDrive, Dropbox, Mega, pCloud.
• Self-hosted: WebDAV / Nextcloud, ownCloud.
• Tradizionali: FTP, SFTP.

Puoi:

• Schedulare i backup via cron (giornaliero, orario, cadenza custom).
• Configurare una retention policy (mantieni gli ultimi N snapshot giornalieri, settimanali, mensili).
• Eseguire backup zero-downtime — gli snapshot di Qdrant e il database SQLite degli utenti vengono catturati in modo consistente senza interrompere l'API.

Il restore è l'operazione inversa contro lo stesso remote: si recupera il bundle, si lancia il comando di restore e l'istanza torna al punto temporale scelto.

Reverse proxy & TLS

Il backend FastAPI ascolta su localhost:8000, il frontend React su localhost:3000. Entrambi vanno messi dietro un reverse proxy che termina il TLS — Caddy, nginx o Traefik vanno tutti bene. Configurazione minimale Caddy:

rag.example.com {
  reverse_proxy /api/* localhost:8000
  reverse_proxy localhost:3000
}

Caddy provisiona e rinnova automaticamente un certificato Let's Encrypt. Per nginx o Traefik basta replicare lo stesso routing: /api/* verso la porta 8000, tutto il resto verso la 3000.

Production checklist

Prima di andare in produzione:

• Frontend e backend dietro reverse proxy con TLS 1.3.
• Backup automatici verso una destinazione esterna configurati via rclone.
• Quote disco e log rotation attive sulle directory di dati e log.
• Monitoring in piedi — Prometheus + node_exporter è una baseline ragionevole; va bene qualsiasi soluzione già in casa.
• Update plan documentato — come si applicano gli aggiornamenti del repo upstream.
• Disaster recovery plan testato end-to-end su un dataset non di produzione.
• JWT secret ruotato rispetto al valore di default.
• Utente admin configurato con password forte.
• Restrizioni di accesso per IP configurate se il threat model lo richiede.

I3K RAG Enterprise è distribuito sotto AGPL-3.0. Il repository sorgente — github.com/I3K-IT/RAG-Enterprise — è il riferimento canonico per script di installazione, parametri di configurazione e percorsi di upgrade supportati.