Air-gappé / on-prem

Ongrid est livré comme un seul tarball auto-contenu précisément pour qu'il marche offline. Il n'y a pas d'apt install, pas de Go-module-fetch-at-build-time sur l'host cible, pas de pull Docker Hub au runtime. Déposez le tarball, exécutez install.sh, et vous avez un manager + flotte d'edges fonctionnels.

Les tradeoffs que vous toucherez en allant air-gappé sont autour du provider LLM, du modèle d'embedding pour le RAG et des upgrades en cours. Cette page est la check-list.

Étape 1 : Télécharger le tarball de release

Depuis un host avec internet, prenez le dernier asset de release :

gh release download v0.7.167 --repo ongridio/ongrid \
    --pattern 'ongrid-*-linux-amd64.tar.xz'
gh release download v0.7.167 --repo ongridio/ongrid \
    --pattern 'ongrid-*-linux-amd64.tar.xz.sha256'
sha256sum -c ongrid-v0.7.167-linux-amd64.tar.xz.sha256

Ou buildez le tarball vous-même avec make package. Dans tous les cas, l'artefact est un seul .tar.xz plus son .sha256.

Déplacez les deux fichiers vers l'host cible via le canal air-gap que vous utilisez (USB sneakernet, serveur d'artefacts interne, bucket S3 signé, etc.).

Étape 2 : Install par tarball

Le tarball s'expand en un répertoire auto-contenu :

ongrid-v0.7.167-linux-amd64/
  install.sh
  upgrade.sh
  docker-compose.yml
  images/
    ongrid.tar              # docker image, saved
    ongrid-web.tar
    frontier.tar
    mysql.tar               # bundled so no Docker Hub pull
    prometheus.tar
    loki.tar
    tempo.tar
    grafana.tar
    searxng.tar
  bin/
    linux-amd64/ongrid-edge
    linux-arm64/ongrid-edge
    darwin-amd64/ongrid-edge
    darwin-arm64/ongrid-edge
    linux-amd64/promtail
    linux-arm64/promtail
    linux-amd64/otelcol-contrib
    linux-arm64/otelcol-contrib
    linux-amd64/node_exporter
    linux-arm64/node_exporter
    linux-amd64/process_exporter
    linux-arm64/process_exporter
  edge/
    apply-pending-upgrade.sh
  .cache/
    bge-base-en-v1.5/       # optional offline RAG embedding model

Exécutez :

tar -xf ongrid-v0.7.167-linux-amd64.tar.xz
cd ongrid-v0.7.167-linux-amd64
sudo ./install.sh

install.sh charge chaque images/*.tar dans le docker local, écrit un .env sensé, lève la stack avec docker compose up -d, et affiche l'URL du nouveau manager. L'host a besoin de Docker Engine + Compose v2 — voir Linux (serveur).

Voir Installation air-gappée pour le pas-à-pas complet avec checksums et premier démarrage.

Étape 3 : Mirror vers un registry privé (optionnel)

Si vous avez un registry de conteneur privé (Harbor / Artifactory / ECR / GCR), et préférez docker pull plutôt que docker load, poussez les images embarquées une fois :

for img in images/*.tar; do
  name=$(docker load -i "$img" | awk -F': ' '/Loaded image/ {print $2}')
  registry_tag="registry.internal/${name}"
  docker tag "$name" "$registry_tag"
  docker push "$registry_tag"
done

Puis écrivez un docker-compose.override.yml qui pointe chaque service vers registry.internal/... au lieu de l'image originale, et vous pouvez déployer sur N hosts sans re-livrer le tarball. Les futures upgrades deviennent « pull du nouveau tag d'image, docker compose up -d ».

Étape 4 : Installation edge dans un réseau air-gappé

L'installer curl-pipe (https://<manager>/install.sh | bash) marche bien à l'intérieur d'un réseau air-gappé tant que les edges peuvent atteindre le manager (port 443 pour le bundle statique + port 40012 pour le tunnel). L'installer télécharge le binaire agent et les quatre binaires de plugin depuis https://<manager>/edge/, que le nginx du manager sert depuis le répertoire ./bin/ bind-mounté.

Si vos edges ne peuvent pas atteindre le manager sur HTTPS — par exemple, les edges sont dans un segment réseau qui n'autorise que le port 40012 — copiez les binaires à la main :

# on each edge host
sudo install -m 0755 ongrid-edge /usr/local/bin/ongrid-edge
sudo mkdir -p /usr/local/lib/ongrid-edge
sudo install -m 0755 promtail otelcol-contrib node_exporter process_exporter \
    /usr/local/lib/ongrid-edge/
# then write /etc/ongrid-edge/ongrid-edge.env and the systemd unit
# (see deploy/install/edge/install.sh for the exact unit content)

Ou, plus robustement : montez un minuscule mirror HTTPS interne qui détient une copie de ./bin/linux-*/ et pointez un install.sh forké dessus.

Étape 5 : Provider LLM

Ongrid n'embarque pas de LLM. Le kernel d'agent appelle un provider upstream — Anthropic, OpenAI, Zhipu, DeepSeek, Gemini, Kimi, ou tout relais compatible OpenAI — sur la connexion internet sortante du manager. Dans un réseau air-gappé, vous avez trois options :

1. Proxy sortant. Posez HTTPS_PROXY=http://your-proxy:3128 dans le bloc env du manager. Tous les appels de provider passent par le proxy.
2. Relais self-hosté compatible OpenAI. Exécutez vLLM / TGI / Ollama / one-api dans votre réseau, pointez ONGRID_OPENAI_BASE_URL dessus, mettez ONGRID_OPENAI_API_KEY à ce que le relais attend. C'est le pattern le plus courant pour les installs entièrement déconnectées.
3. Provider custom dans l'UI. Settings → Models → Custom (compatible OpenAI) vous donne le même câblage sans redémarrage.

Si vous voulez utiliser Zhipu (GLM) contre un endpoint hosté Tencent Cloud à l'intérieur de la Chine, posez ONGRID_ZHIPU_BASE_URL à l'endpoint régional et ONGRID_ZHIPU_API_KEY à votre clé — pas de proxy nécessaire, GLM est joignable à l'intérieur du réseau Chine-continentale.

Étape 6 : RAG offline (le modèle d'embedding)

L'ingestion de base de connaissances a besoin d'un modèle d'embedding. Par défaut, le manager appelle l'API d'embedding GLM (embedding-3) qui a besoin d'internet. Pour un déploiement entièrement offline, basculez vers le profil embedding local :

ONGRID_EMBEDDING_PROVIDER=local
ONGRID_EMBEDDING_LOCAL_MODEL_PATH=/var/lib/ongrid/embeddings/bge-base-en-v1.5

Le tarball de release livre le modèle BAAI/bge-base-en-v1.5 sous .cache/bge-base-en-v1.5/ (~400 Mo). Le script d'install le copie dans le volume nommé au premier boot. Si vous avez sauté make fetch-embedding-model en construisant le tarball, le modèle est absent et l'embedding échouera — exécutez cette étape une fois et re-packagez.

Le vault intégré par défaut d'Ongrid (github.com/ongridio/vault) est public et contient les runbooks de baseline livrés dans le seed RAG embarqué. Le synchroniser nécessite d'atteindre GitHub. Dans un réseau air-gappé vous pouvez :

• Vendorer le vault dans votre propre serveur Git interne et mettre à jour ONGRID_VAULT_REPO_URL.
• Ou, sauter la sync de vault entièrement — le seed embarqué (environ 96 playbooks) vit à l'intérieur du binaire et est toujours disponible.

Étape 7 : Upgrades

Deux chemins :

1. Même mécanisme de tarball. Téléchargez le nouveau tarball sur un host connecté à internet, sneakernet-le, exécutez ./upgrade.sh. C'est install.sh moins le bootstrap — chargement d'images + docker compose up -d. Les agents edge prennent les binaires agent + plugin matchants la prochaine fois qu'ils se reconnectent (staging de bundle entier ADR-024).
2. Pull de registry privé. Si vous avez mirroré les images (Étape 3), docker compose pull && docker compose up -d suffit. Les edges ont encore besoin des nouveaux binaires agent + plugin, qu'ils fetch depuis le chemin statique /edge/ du manager — ça se met à jour automatiquement quand vous swappez le répertoire bin/ livré par tarball.

Ce qui NE marche PAS air-gappé

• Auto-sync du vault intégré sans mirror — le repo vault vit sur GitHub.
• LLMs hostés du provider sans proxy sortant ou relais — il n'y a pas de LLM local livré.
• Le profil d'embedding GLM par défaut — basculez vers local (voir Étape 6).
• Installs de skill du marketplace public (ADR-017) — pointez vers un registry privé à la place.

Tout le reste, y compris le kernel d'agent complet, l'evaluator d'alerte, le pipeline de télémétrie et l'UI de chat, tourne entièrement offline.