Vai al contenuto

Per iniziare

Installazione e self-host

Installazione in produzione del singolo binario Olivares AI — nessuna credenziale predefinita, TLS attivo di default, probe /readyz e /livez.

Ultimo aggiornamento:

Olivares AI viene distribuito come un singolo binario statico con la console web incorporata. Il piano di controllo — la parte che osserva, governa e registra gli agenti AI sulla tua infrastruttura — gira nel tuo perimetro e può essere air-gapped. Questa pagina copre l’installazione in produzione: un singolo host, impostazioni sicure di default, probe di salute, e la scelta del datastore che conta per i deployment multi-tenant.

Se vuoi solo dare un’occhiata prima, il quickstart avvia un estate demo sintetico in circa cinque minuti. Questa pagina è la postura reale.

Ottenere il binario

Non c’è un URL di download pubblico da copiare qui. Ottieni il binario olivares in uno dei due modi:

  • Un artefatto di rilascio firmato — verificalo prima di eseguirlo. Vedi verificare un rilascio per la catena di firma e provenienza.
  • Compilazione dai sorgenti — il datastore è pure-Go SQLite, quindi non serve una toolchain C. Un task build produce ./bin/olivares con la web UI e i connettori first-party incorporati; olivares version conferma cosa hai compilato.

In entrambi i casi ottieni un singolo file. Installalo e crea un utente di servizio dedicato anziché eseguirlo come root.

Impostazioni sicure di default

I default sono scelti in modo che un’installazione nuova sia sicura prima di toccare qualsiasi flag.

| Default | Comportamento | |—-|—-| | Credenziali | Nessuna. Il primo avvio stampa un token di setup unico e monouso (prefisso olst_); crei il primo amministratore con esso. | | TLS | Attivo. Senza --tls-cert/--tls-key, il motore genera un certificato self-signed nella directory dati e registra il suo fingerprint_sha256. --insecure (testo in chiaro) è solo per sviluppo locale. | | Bind | Loopback. --listen è impostato di default su 127.0.0.1:8443 e gRPC su 127.0.0.1:8444; esponili deliberatamente, dietro il tuo ingress e TLS. |

Un primo avvio minimale:

olivares serve \
  --listen 127.0.0.1:8443 \
  --grpc-listen 127.0.0.1:8444 \
  --data-dir /var/lib/olivares

La directory dati contiene il datastore, la chiave di firma dell’audit e il materiale TLS. Fai il backup e proteggila con permessi restrittivi.

Utilizzare il token di setup unico

Un’installazione nuova non ha credenziali predefinite. Al primo avvio, finché non esistono utenti, il motore genera un token di setup monouso e lo stampa solo su stdout — mai nei log:

=== FIRST-BOOT SETUP ===
No users exist yet. Create the first administrator:
  POST /v1/setup  {"token":"olst_…","email":"you@example.com","password":"..."}
This token is shown ONCE and is single-use.
========================

Solo l’hash del token viene memorizzato, quindi un token perso non può essere recuperato e un riavvio non lo ristampa. Su un’installazione completamente nuova senza utenti, rimuovere il token memorizzato dalla directory dati e riavviare ne genera uno nuovo. Quel recupero funziona solo finché non esistono utenti, quindi non può mai prendere il controllo di un’installazione configurata.

Dopo aver creato il primo amministratore, l’endpoint di setup viene chiuso definitivamente.

Probe di salute

Il listener HTTP espone due probe con semantiche deliberatamente diverse. Collegale alla probe Kubernetes corrispondente — confondere le due causa loop di riavvio o routing obsoleto.

/livez è la liveness. Non esegue nessun controllo di dipendenza: se il processo può rispondere, è vivo. Una dipendenza in errore non deve mai attivare un riavvio di liveness.

curl -ks https://127.0.0.1:8443/livez
# {"status":"ok"}

/readyz è la readiness, ed è il segnale di disponibilità su cui un load balancer dovrebbe fare drain. Restituisce 503 in due casi, distinti nel body per i tuoi log:

  • Datastore irraggiungibile — {"status":"unavailable","store":"down"}. Il ping del datastore viene eseguito con un timeout breve, così un backend bloccato fa drain dell’istanza anziché bloccarla.
  • Non lo scrittore attivo — {"status":"standby","store":"up","leader":false}. In un cluster attivo-passivo uno standby restituisce 503 qui cosi il Service smette di instradare verso di esso, senza riavviarlo (quello è il lavoro di /livez — uno standby caldo deve restare attivo per subentrare). Quando il leader muore, uno standby acquisisce la leadership e questo passa a 200, cosi il traffico segue automaticamente il nuovo leader.

Quando il motore è pronto restituisce 200:

{"status":"ok","store":"up","leader":true,"setup_required":false}

setup_required viene riportato per l’osservabilita ma non fa fallire la readiness — un motore appena avviato è pronto per essere configurato. Su un datastore a singolo nodo lo scrittore e sempre attivo, quindi /readyz traccia semplicemente la raggiungibilità del datastore.

Scegliere un datastore

Il datastore viene selezionato con --engine. Scegli in base alla topologia, non alla preferenza.

SQLite (default)

Il datastore SQLite incorporato pure-Go non necessita di nulla di esterno ed e la scelta giusta per un singolo nodo, un laboratorio, un estate piccolo o un’installazione air-gapped. Tutto lo stato risiede nella directory dati.

Postgres (multi-tenant)

Per deployment multi-host o multi-tenant, usa Postgres. Non connetterti come superuser o come ruolo con BYPASSRLS. L’isolamento dei tenant viene applicato da FORCE ROW LEVEL SECURITY, e Postgres bypassa silenziosamente tutta la row-level security per tali ruoli — il che lascerebbe solo il predicato a livello applicativo tra i tenant. Il motore rifiuta di avviarsi con un ruolo privilegiato a meno che non passi esplicitamente --allow-privileged-db-role (solo single-tenant o dev).

Configura invece un ruolo dedicato a privilegi minimi — NOSUPERUSER NOBYPASSRLS NOCREATEROLE NOCREATEDB. Possiede il proprio database cosi può applicare le migrazioni dello schema; FORCE ROW LEVEL SECURITY applica la policy del tenant anche al proprietario della tabella, cosi un ruolo proprietario-ma-non-bypassing resta completamente isolato.

olivares serve --engine postgres \
  --dsn "postgres://olivares_app:$DB_PASSWORD@db:5432/olivares?sslmode=verify-full" \
  --data-dir /var/lib/olivares

Usa sslmode=verify-full e una password SCRAM forte. Le letture System genuinamente cross-tenant (l’elenco delle organizzazioni, la copertura checkpoint multi-tenant) necessitano di un ruolo separato: configura uno che sia NOSUPERUSER BYPASSRLS — privilegi minimi ma capace di leggere tra i tenant — e punta --admin-dsn verso di esso. Omettilo per i deployment single-tenant e quelle letture sono semplicemente limitate da RLS.

Prima di considerarlo finito

Due cose decidono se le tue evidenze sopravvivono a un incidente:

  • Fai il backup della chiave di firma dell’audit fuori dal server. Firma il registro di audit append-only; se viene persa, il registro non può più essere ri-verificato. Il motore avvisa al primo avvio — non c’e un escrow applicato.
  • Conserva una copia fuori dal server della chiave pubblica del registro. Quella copia esterna e ciò che rende la verifica dell’audit resistente dopo la compromissione di un host.

Poi pianifica backup reali della directory dati.

Cosa gira dove

Solo il piano di controllo e tuo da posizionare — air-gapped se lo desideri. I collector (piano dati) girano sempre sulla tua infrastruttura. Un avvertimento che vale la pena dichiarare chiaramente: Olivares governa e registra l’uso di Claude, ma l’inferenza di Claude non e self-hosted — raggiunge l’API di Anthropic (direttamente o tramite Bedrock, Vertex o Foundry). Solo i modelli genuinamente self-hosted funzionano offline. Vedi la pagina trasparenza e limiti per il confine completo.

Prossimi passi

Cerca nella documentazione