Installation & déploiement¶

Avant de mettre à niveau une base existante, suivez la procédure de migration UUID. Tous les anciens réplicas et workers doivent être arrêtés.

Xolo est un binaire Go unique (xolo-server) qui embarque le serveur HTTP, l'interface web d'administration et le proxy LLM. Les plugins sont des binaires séparés, découverts au démarrage dans un répertoire dédié.

Prérequis¶

• Un secret de 32 octets (XOLO_SECRET_KEY) pour chiffrer les clés API des fournisseurs en base. Générez-le avec openssl rand -hex 32.
• Un fournisseur d'authentification : OIDC générique, ou l'un des fournisseurs intégrés (Google, GitHub, Gitea). Voir Configuration.
• Une base SQLite (par défaut data.sqlite, dans le répertoire de travail) — aucune base externe n'est requise pour démarrer.

Option 1 : image Docker¶

L'image officielle est publiée sur ghcr.io/xolo-gateway/xolo-server à chaque tag sémantique (vX.Y.Z), avec en plus le tag latest.

XOLO_SECRET_KEY=$(openssl rand -hex 32) # Devrait rester stable dans le temps
docker run -d \
  --name xolo \
  -p 3002:3002 \
  -e XOLO_SECRET_KEY="${XOLO_SECRET_KEY}" \
  -e XOLO_HTTP_BASE_URL=https://xolo.example.com \
  -e XOLO_HTTP_AUTHN_DEFAULT_ADMINS=admin@example.com \
  -v xolo-data:/data \
  ghcr.io/xolo-gateway/xolo-server:latest

Deux points spécifiques à l'image :

• XOLO_STORAGE_DATABASE_DSN vaut /data/data.sqlite par défaut : montez un volume sur /data pour persister la base entre redémarrages. Pour utiliser PostgreSQL à la place, positionnez cette variable sur un DSN postgres://… (voir Configuration) ; le volume /data devient alors inutile.
• XOLO_PLUGINS_DIR vaut /plugins par défaut. L'image embarque déjà les plugins officiels (time-restriction, dummy-model, fuzzy-evaluator, request-inspector, complexity-scorer, text-classifier, llm-classifier, energy-estimator, budget-pressure, script-processor, pseudonymizer, mcp-bridge, system-prompt) à cet emplacement.
• Le port exposé est 3002.

Sondes de santé¶

Chaque instance répond sans authentification sur deux chemins, à destination d'un répartiteur de charge ou d'un orchestrateur :

/readyz répond 503 tant que la base est injoignable : l'instance sort du répartiteur sans être redémarrée. Son résultat est partagé pendant 0,8 s : un afflux de sondes ne coûte qu'une vérification à la base. Les deux chemins passent avant la résolution du locataire, la journalisation, les métriques HTTP et la limitation de débit : une sonde vise l'instance par son adresse, qui n'est le domaine d'aucun locataire.

Sur PostgreSQL, /readyz passe par une connexion qui lui est propre, hors du pool de l'application : un pool saturé par le trafic ne fait pas sortir toutes les instances du répartiteur en même temps. La sonde dit si la base répond, pas si l'instance est occupée. Comptez une connexion de plus par instance.

healthcheck:
  test: ["CMD", "wget", "-qO-", "http://localhost:3002/readyz"]

Pour un déploiement avec docker-compose, ajoutez un service pointant vers cette image, un volume nommé pour /data, et les variables d'environnement décrites dans Configuration.

Option 2 : binaire compilé depuis les sources¶

git clone https://github.com/xolo-gateway/xolo.git
cd xolo
cp .env.dist .env
# éditez .env : XOLO_SECRET_KEY, XOLO_HTTP_AUTHN_DEFAULT_ADMINS, un fournisseur d'auth…
make build          # compile bin/server et les plugins dans bin/plugins/
make CMD='bin/server' run-with-env

make build enchaîne build-server, build-migrate, build-frontend et la compilation de tous les plugins présents sous plugins/. Si vous modifiez des fichiers .templ ou le CSS Tailwind, lancez make generate avant make build.

Pour un rechargement à chaud en développement, make watch (nécessite .env et l'outil modd, récupéré automatiquement dans tools/).

Premier démarrage¶

1. Renseignez XOLO_HTTP_AUTHN_DEFAULT_ADMINS avec l'adresse email du ou des comptes qui doivent être administrateurs dès leur première connexion.
2. Connectez-vous via le fournisseur d'authentification configuré : le compte correspondant à cette adresse email obtient automatiquement les droits d'administration.
3. Créez votre première organisation, puis suivez les prochaines étapes : invitations, rôles, fournisseurs, budget.

Pour aller plus loin¶