Deployment

Il motore è un binario su una macchina. Questo elimina quasi tutto quello che di solito si chiama lavoro di deployment, e lascia una lista corta di decisioni che contano davvero: dove stanno i suoi dati, se può ricadere sulla CPU, come viene esposto, e come si ripristina quando qualcosa va storto.

I passi di installazione sono nell'avvio rapido.

Configurazione

Le impostazioni arrivano dall'ambiente o da un file .env accanto al binario, usando __ per separare i livelli. Una sola non ha default:

AUTH__JWT_SECRET=…            # obbligatoria — firma i token di sessione

Tutto il resto è opzionale:

SERVER__PORT=8000
AUTH__ADMIN_DEFAULT_PASSWORD=…   # altrimenti ne viene generata una casuale e scritta nel log
QDRANT__COLLECTION=rag_documents
EMBEDDINGS__REQUIRE_GPU=false    # true = rifiuta di partire senza CUDA invece di
                                 # ricadere in silenzio su una CPU molto più lenta
DATA__DIR=/percorso/dati         # default: la directory del binario
BACKUP__DIR=…                    # default: {DATA__DIR}/backups
RUST_LOG=info

In produzione imposta EMBEDDINGS__REQUIRE_GPU

Senza, una configurazione CUDA rotta degrada silenziosamente su CPU e l'indicizzazione passa da secondi a minuti — facile non accorgersene finché qualcuno non si lamenta. Il fallback viene sempre registrato a livello error ed esposto su GET /api/info, ma su una macchina di produzione di solito si preferisce un errore netto.

Dove stanno i dati

DATA__DIR di default è la directory che contiene l'eseguibile, e contiene tutto: i componenti scaricati, lo storage di Qdrant, il database SQLite e i documenti caricati.

Puntalo su un volume dedicato prima del primo avvio. Farlo dopo significa che i componenti vengono riscaricati nel nuovo percorso, dove non esiste ancora nulla.

Dimensionamento

Meglio misurare che stimare. Il binario si cronometra da solo, sul tuo hardware e sui tuoi documenti:

./i3k-rag-engine --bench /percorso/documento.pdf

Il report Markdown che produce scompone il tempo per fase — estrazione, suddivisione, embedding, scrittura, prefill, decode — e ti dice se sei corto di GPU, di CPU o di niente. --bench-live registra invece una sessione reale e produce il report alla chiusura.

Come punto di partenza:

Risorsa	Indicazione
GPU	Una GPU NVIDIA viene rilevata e usata automaticamente, per la generazione e — dove richiesto — per l'embedding. Senza, gira tutto su CPU
RAM	16 GB minimi, 32 GB per stare comodi
Disco	30 GB liberi prima del primo avvio, poi in crescita col corpus
Sistema operativo	Linux x86_64, Linux ARM64 oppure Windows a 64 bit
Rete	Solo per il primo avvio

Come esporlo

Il motore parla HTTP in chiaro su SERVER__PORT. Mettici davanti un reverse proxy e termina lì il TLS — nginx, Caddy o qualunque cosa la tua organizzazione già usi. Non esporre direttamente la porta del motore su una rete non fidata.

Imposta AUTH__ADMIN_DEFAULT_PASSWORD prima del primo avvio, oppure recupera subito dal log quella generata: viene stampata una volta sola e non viene più mostrata.

Backup e ripristino

Un archivio giornaliero schedulato contiene il database SQLite e uno snapshot di Qdrant presi insieme, così i due sono coerenti fra loro. Un endpoint amministrativo ripristina un archivio sull'installazione in esecuzione.

Gli archivi sono file locali sotto BACKUP__DIR. Non viene caricato niente da nessuna parte, il che significa che le copie fuori sede restano una tua responsabilità: punta su quella directory gli strumenti di backup che già usi, esattamente come faresti con qualunque altro volume dati.

Testa il ripristino, non il backup

Un backup mai ripristinato è un'ipotesi. Provane uno su una macchina di scorta prima di doverlo fare sotto pressione — l'archivio è pensato perché database e snapshot vettoriale tornino come coppia coerente, ed è proprio questa la proprietà che vale la pena verificare una volta.

Funzionamento air-gapped

Dopo il primo avvio il motore non ha bisogno di rete: ogni componente che usa è già stato scaricato e verificato.

Per una macchina che non avrà mai connettività, esegui il primo avvio su una macchina di staging con la stessa piattaforma, poi sposta l'intera DATA__DIR. Siccome i componenti vengono riscaricati solo se mancanti o se non superano la verifica, il motore trova tutto al suo posto e parte senza contattare nessuno.

Aggiornamento

Estrai la nuova release sopra l'installazione esistente — stessa directory, sovrascrivendo binario, .env.example e frontend/dist/. Tutto ciò che è già stato scaricato viene riusato; vengono riscaricati solo i componenti la cui versione dichiarata è effettivamente cambiata. Il tuo .env non viene toccato, perché l'archivio contiene soltanto .env.example.

Leggi il CHANGELOG prima di aggiornare. La linea 0.1.x è una base di codice nuova, il cui layout di storage e la cui superficie HTTP non sono ancora stabilizzati.

Compilare dai sorgenti

Quasi mai serve: gli archivi di release sono autosufficienti. Se vuoi modificare il motore o compilarlo per una piattaforma che non pubblichiamo, BUILD.md elenca le dipendenze di sistema e i feature flag.

cargo build --release --features cuda

CUDA è l'unica dipendenza di sistema in compilazione, e solo per quella feature.