Ospitare Kisuno in proprio

Che cosa Le serve

Per Kisuno servono una macchina Ubuntu con Docker Engine e Compose v2, un record DNS che punti ad essa e una chiave API del Suo gateway di modelli. Lo stack gira interamente su questo unico host, poiché il carico di calcolo dei modelli linguistici è a carico del fornitore di inferenza.

Server e requisiti di sistema

Il minimo è 2 vCPU, 4 GB di RAM, 40 GB di disco e Ubuntu 22.04 LTS. Per l’esercizio produttivo si raccomandano 4 vCPU, 16 GB di RAM e 200 GB di disco su Ubuntu 24.04 LTS; la ripartizione per dimensione del team è riportata nella tabella sottostante. La sandbox di codice rinforzata richiede inoltre la virtualizzazione annidata.

Sotto carico cresce praticamente soltanto la memoria dell’applicazione di chat, mentre l’utilizzo della CPU resta prossimo allo zero. Le immagini occupano una tantum circa 5-6 GB e vengono condivise tra le istanze sulla stessa macchina. In seguito crescono soprattutto i file caricati: il primo limite nell’esercizio è lo spazio su disco.

Che cosa non Le serve

• Nessun Kubernetes. Docker Compose è l’architettura supportata, non viene fornito alcun chart Helm.
• Nessuna GPU per il livello applicativo. L’hardware GPU serve solo a chi desidera eseguire in aggiunta modelli linguistici in locale.
• Nessun account presso di noi. L’installazione avviene senza registrazione, senza chiave di licenza e senza server di licenze.
• Nessun hyperscaler e nessuna banca dati gestita. È sufficiente una qualsiasi VM Ubuntu; banca dati e indice di ricerca girano nello stesso stack.

Installazione in tre passaggi

L’installazione di Kisuno consiste in due script e in una voce nel file .env. Su una macchina in cui Docker è già in esecuzione, il primo passaggio non è necessario.

Passo 1: preparare il server

Il repository GitHub è in arrivo a breve. Chi desidera iniziare già oggi richiede un accesso all’istanza gestita tramite il modulo. I comandi mostrano come si presenta poi l’installazione: clonare il repository, passare alla directory distribution, avviare lo script di preparazione.

cd distribution
./setup-server.sh

Lo script è idempotente e installa Docker Engine con Compose v2 dalla fonte ufficiale di Docker, poiché il pacchetto Ubuntu docker.io non include Compose v2. Si aggiungono la rotazione dei log, le regole di firewall per le porte 22, 80 e 443, lo swap, il fuso orario e gli aggiornamenti di sicurezza automatici. Al termine occorre effettuare nuovamente il login.

Passo 2: installare lo stack

./install.sh --profiles production

L’installer verifica Docker e Compose v2, crea il file .env dal modello, genera tutti i secret, predispone le directory dati e la rete della sandbox, scarica le immagini e avvia lo stack. Il profilo production include il reverse proxy, che ottiene automaticamente il certificato TLS.

Passo 3: inserire l’accesso ai modelli

# .env
MODEL_API_KEY=<euer-api-key>

docker compose up -d

Senza chiave lo stack si avvia comunque, ma la chat segnala una chiave API mancante. L’accesso è liberamente selezionabile, poiché Kisuno dialoga con qualsiasi gateway compatibile con OpenAI. Nell’istanza gestita offriamo i modelli attuali di OpenAI (ChatGPT) e Anthropic (Claude); vengono eseguiti nel data center AWS di Francoforte. AWS è un’azienda statunitense, quindi lo US CLOUD Act si applica anche con server a Francoforte, e lo diciamo apertamente. Per i clienti con requisiti elevati di protezione dei dati sono disponibili modelli aperti di punta come GLM, Kimi e DeepSeek, gestiti da aziende europee su server in Europa; lì lo US CLOUD Act non si applica. In caso di self-hosting sceglie personalmente ogni fornitore di questa catena e indica il Suo endpoint.

Da quali servizi è composto lo stack

Lo stack si basa su un file docker-compose.yml; diversi servizi sono collocati dietro profili opzionali e si avviano solo se li attiva. Ogni servizio è un progetto open source noto e può essere ispezionato, sostituito o disattivato singolarmente.

L’applicazione di chat si basa su LibreChat con licenza MIT e fornisce interfaccia, account, conversazioni, caricamento di file e collegamento ai modelli. Kisuno mantiene questa parte vicina all’upstream, affinché gli aggiornamenti di sicurezza del progetto restino recepibili.

MongoDB memorizza conversazioni, account, ruoli e impostazioni, come container nello stesso stack e sul Suo disco. Non esiste alcun servizio di banca dati esterno verso cui i contenuti potrebbero defluire.

Meilisearch fornisce la ricerca full text sulle proprie conversazioni. L’indice risiede in locale e può essere ricostruito; la telemetria di Meilisearch è disattivata di fabbrica.

L’API RAG con pgvector è opzionale e si aggiunge tramite il profilo filesearch. L’API RAG genera gli embedding dei file che gli utenti caricano nella chat e restituisce al modello i passaggi pertinenti durante la risposta.

Il gateway MCP si colloca tra l’applicazione di chat e ogni sistema collegato e decide per ogni chiamata di strumento se sia consentita. La valutazione avviene in quest’ordine: singolo utente, ruolo, gruppo, impostazione predefinita del server. Ogni chiamata viene registrata e, se la verifica non riesce, l’accesso viene negato.

Il pannello di amministrazione è l’interfaccia per utenti, ruoli, gruppi, regole di accesso, log di audit e budget. Fa parte dello stack, resta in ascolto solo in locale ed è raggiungibile dall’esterno esclusivamente tramite il reverse proxy.

La sandbox di codice esegue il codice generato dal modello, così che da una richiesta nasca un vero file scaricabile. Viene affiancata come stack Compose separato e collegata tramite una rete Docker dedicata. Sono disponibili due backend: uno leggero come impostazione predefinita e uno rinforzato basato su una microVM, che richiede la virtualizzazione annidata sull’host. Un proxy di uscita con lista di autorizzazione è in corso di realizzazione.

SearXNG fornisce la ricerca web dal Suo stack, senza account presso un servizio di ricerca. Detto con franchezza: SearXNG inoltra i termini di ricerca a motori di ricerca esterni, senza trasmettere l’identità dell’utente. Conversazioni e file non lasciano la macchina.

Caddy termina il TLS, ottiene automaticamente i certificati non appena il record DNS punta alla macchina ed è l’unico servizio sulle porte 80 e 443. Per l’esercizio dietro un WAF o con un’autorità di certificazione interna sono incluse apposite varianti.

Tre modelli operativi, un’unica architettura

Esistono tre modelli operativi e una sola architettura: gestito da Lei, nel Suo cloud, eventualmente tramite il Suo fornitore IT, oppure gestito da noi. In tutti e tre i casi lo stack è il medesimo. Cambia soltanto chi detiene il root, chi amministra le chiavi e chi esegue aggiornamenti e backup.

Gestito da Lei

Lei gestisce la macchina, detiene il root, amministra le Sue chiavi ed esegue autonomamente aggiornamenti e backup. Il software non costa nulla, un abbonamento di supporto è facoltativo. Questo modello è il metro di misura: ciò che un amministratore esterno riesce ad avviare con due comandi sostiene anche gli altri modelli.

Nel Suo cloud

Kisuno gira su qualsiasi VM Ubuntu, nel proprio centro di calcolo così come presso un fornitore cloud svizzero o europeo. Non esiste alcun vincolo a un hyperscaler. Chi come fornitore IT ospita per i propri clienti utilizza la stessa architettura: uno stack per cliente.

Gestito da noi

Ci occupiamo di installazione, aggiornamenti, backup e monitoraggio e gestiamo l’istanza in centri di calcolo certificati ISO 27001 di Green a Lupfig, in Svizzera. I certificati sono di Green, non di Kisuno; la certificazione ISO 27001 propria di Kisuno è in corso.

Più istanze su una macchina

Il confine tra i clienti è lo stack Compose, non la VM: ogni istanza dispone di banca dati propria, indice di ricerca proprio, file caricati propri, secret propri, rete Docker propria e sandbox di codice propria. Per i team piccoli, da tre a cinque istanze possono quindi condividere la stessa VM.

Possono essere condivisi le immagini Docker e un reverse proxy comune. Non vanno mai condivisi banca dati, file caricati, secret, rete della sandbox e chiave del fornitore di modelli: una chiave condivisa rende impossibile attribuire il consumo per cliente, e una rete della sandbox condivisa annulla la separazione proprio dove viene eseguito codice altrui.

Come funzionano gli aggiornamenti e che cosa conta nell’esercizio

Gli aggiornamenti sono riproducibili, perché l’immagine applicativa è fissata su un digest anziché su un tag mobile e gli altri servizi girano su versioni fisse. Un rilascio di Kisuno è quindi una combinazione testata di immagine applicativa e servizi, e due istanze sulla stessa macchina possono usare versioni diverse.

git pull
./backup.sh backup
./install.sh --migrate

L’opzione --migrate lascia intatto il file .env e ricostruisce i servizi propri. Prima di ogni aggiornamento serve un backup, subito dopo un breve test funzionale. Il ritorno alla versione precedente avviene tramite lo stato precedente del file Compose.

Nell’esercizio corrente contano due aspetti: la rotazione dei log configurata da setup-server.sh e lo spazio su disco, con un allarme a partire dal 70 per cento di occupazione. Le domande ricorrenti su esercizio, aggiornamenti e salvataggio dei dati trovano risposta nelle domande frequenti.

Un solo script per backup, ripristino e migrazione

Un unico script copre backup, ripristino e migrazione del server: backup.sh crea un archivio a partire dal dump della banca dati, dal file .env e dai file caricati, e provvede anche al ripristino. Una migrazione si riduce quindi a un backup sul vecchio server, alla copia dell’archivio e al ripristino su quello nuovo.

./backup.sh backup            # Archiv erzeugen
./backup.sh list              # vorhandene Archive
./backup.sh restore <archiv>  # ersetzt die Datenbank, fragt vorher nach

L’archivio contiene secret e conversazioni e viene salvato con permessi restrittivi. Non deve mai finire in un repository né, non cifrato, in un cloud di terzi. L’indice di ricerca non viene incluso nel backup, perché può essere ricostruito dalla banca dati.

L’errore più costoso durante una migrazione consiste nel far rigenerare le chiavi di cifratura invece di riprenderle dal vecchio file .env. Tutte le credenziali salvate nella banca dati diventano allora illeggibili. Con i valori ripresi, la migrazione resta una finestra di manutenzione di 15-30 minuti.

Due regole tratte dall’esercizio: replicare la destinazione del backup al di fuori della macchina e testare almeno una volta il ripristino.

Licenza: che cosa significa MIT in concreto

Kisuno uscirà con licenza MIT a breve; l’applicazione di chat sottostante LibreChat lo è già oggi. Il self-hosting è gratuito, già a partire da un utente e senza registrazione presso di noi. Che cosa significhi nel dettaglio, e perché sia la differenza decisiva nel confronto con altre piattaforme:

• Nessun limite di postazioni. Che sull’istanza lavorino 3 o 300 persone non cambia nulla ai fini della licenza.
• Nessun obbligo di branding. Nome, logo e colori sono configurazione, anche per l’impiego commerciale.
• Nessun feature gating. Gestione dei diritti, log di audit, budget e collegamenti ai sistemi provengono dalla stessa sorgente aperta.
• Codice sorgente aperto. La base LibreChat è già oggi consultabile pubblicamente; stack, script e servizi saranno pubblicati con licenza MIT a breve e saranno allora consultabili, forkabili e verificabili, anziché basarsi su una promessa.

Sul piano commerciale sosteniamo il modello con l’esercizio e l’assistenza, non con le licenze. Per questo è aperta anche la via di ritorno dall’esercizio gestito a quello autonomo: stessa architettura, stesso archivio.

Domande frequenti sull’esercizio autonomo