Installation air-gappée

Ongrid est conçu pour s'installer entièrement offline. Chaque tarball de release livre :

• L'image docker du manager ongrid,
• L'image docker ongrid-web (frontend + nginx),
• L'image docker du broker singchia/frontier,
• Les quatre binaires de plugin edge (promtail, otelcol-contrib, node_exporter, process_exporter) pour linux/amd64 et linux/arm64,
• Les binaires ongrid-edge par arch,
• Le modèle d'embedding offline optionnel (fast-bge-small-zh-v1.5) pour la base de connaissances si vous avez exécuté make fetch-embedding-model avant make package.

Rien ne tire de Docker Hub, GitHub ou d'une API vendor au moment de l'install. Les seules dépendances externes au runtime sont les endpoints d'API LLM que vous avez configurés — pour un setup entièrement air-gappé, pointez-les vers un relais on-prem vLLM / Ollama / OpenRouter.

Cette page couvre le workflow pour les environnements qui ne peuvent pas atteindre l'internet public.

Télécharger le tarball sur un host connecté

Sur une workstation qui a internet :

VER=v0.7.159

gh release download "$VER" \
    --repo ongridio/ongrid \
    -p 'ongrid-*-linux-amd64.tar.xz*'

Vous obtiendrez deux fichiers :

ongrid-v0.7.159-linux-amd64.tar.xz          # ~380 MB (xz compressed)
ongrid-v0.7.159-linux-amd64.tar.xz.sha256   # the sidecar

Uploads GitHub via Clash

Les gros assets de release se font reset à mi-parcours sur les proxies Clash. Si vous téléchargez et que le tarball arrive incomplet, essayez avec NO_PROXY=objects.githubusercontent.com en direct. Vérifiez toujours le sha256 (voir étape suivante).

Vérifier le sha256

Avant de faire quoi que ce soit d'autre :

sha256sum -c ongrid-v0.7.159-linux-amd64.tar.xz.sha256
# → ongrid-v0.7.159-linux-amd64.tar.xz: OK

Si cela échoue, ne continuez pas. Re-téléchargez.

Transférer vers le host air-gappé

Le chemin approuvé chez vous. Clé USB, dépôt d'artefacts interne, SFTP via un jumpbox. Les deux fichiers voyagent ensemble ; vous pouvez re-vérifier le sha256 après le transfert.

# On the destination host:
sha256sum -c ongrid-v0.7.159-linux-amd64.tar.xz.sha256

Installer

Identique à l'installation serveur — pas de flags requis pour l'air-gappé, l'installer ne tend jamais la main :

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

install.sh fait :

• docker load les trois images embarquées (images/ongrid.tar, images/frontier.tar, images/ongrid-web.tar).
• Stage les configs, met en place les dirs de données host, génère le cert TLS auto-signé (utilise openssl local ; pas de CA externe nécessaire).
• Câble .env depuis le template, génère des secrets aléatoires forts in-place, demande ONGRID_PUBLIC_URL.
• docker compose up -d, sonde /healthz.

Vous ne devriez voir aucune ligne de log « downloading... ».

Héberger l'URL d'install on-prem

Quand les edges s'installent, ils font curl https://<manager>/install.sh | bash. L'install.sh qu'ils récupèrent est servi par le manager lui-même — spécifiquement par nginx depuis /opt/ongrid/edge/install.sh. Il n'y a pas de GitHub ou autre dépendance externe dans le chemin d'install edge.

Le même nginx sert :

Chemin sur nginx	Quoi
/install.sh	Le script install.sh edge.
/edge/ongrid-edge-linux-amd64	Le binaire de l'agent edge.
/edge/ongrid-edge-linux-arm64	Idem, arm64.
/edge/promtail-linux-amd64	Binaire de plugin.
/edge/otelcol-contrib-linux-amd64	Binaire de plugin.
/edge/node_exporter-linux-amd64	Binaire de plugin.
/edge/process_exporter-linux-amd64	Binaire de plugin.
/edge/apply-pending-upgrade.sh	Hook ExecStartPre ADR-024.
/edge/edge-bundle-linux-amd64-<ver>.tar.gz	Bundle d'upgrade.
/edge/edge-bundle-linux-amd64-<ver>.tar.gz.sha256	Sidecar.

Tous ceux-ci atterrissent dans /opt/ongrid/edge/ quand install.sh tourne et sont servis en lecture seule par le conteneur nginx. Rien d'autre n'est requis.

Installation edge (air-gappée)

La one-liner standard fonctionne tant que l'edge peut atteindre le manager :

curl -k -sSL https://manager.internal/install.sh | sudo bash -s -- \
    --access-key=AK_xxxxxxxxxxxxxxxx \
    --secret-key=SK_yyyyyyyyyyyyyyyy \
    --server-edge-addr=manager.internal:40012 \
    --server-http-addr=manager.internal:443

Si vous avez un host edge qui ne peut pas atteindre le manager directement mais peut atteindre un mirror d'artefacts interne, vous pouvez :

1. Mirror les chemins /install.sh, /edge/* du manager sur votre webserver interne.
2. Exécutez la one-liner en pointant vers l'URL de ce mirror.
3. L'agent aura encore besoin de --server-edge-addr et --server-http-addr pointant vers le vrai manager — le mirror n'héberge que les artefacts d'install, pas le tunnel.

C'est utile pour les setups « l'edge ne peut parler au manager que sur TCP 40012 + un ensemble curé de ports » où TCP 443 vers le manager n'est pas disponible mais un webserver corporate l'est.

Le plan de données a encore besoin de HTTPS vers le manager

Les logs et traces poussent directement de chaque edge vers https://<manager>/loki/api/v1/push et https://<manager>/v1/traces. Si votre edge ne peut pas atteindre le manager sur 443, ces plugins échoueront. L'agent lui-même paraîtra sain (il n'a besoin que de 40012), mais le plan de données sera silencieux — assurez-vous que 443 est ouvert sur le chemin edge → manager.

Providers de modèle air-gappés

Les slots par défaut ONGRID_*_API_KEY= pointent vers des URLs de vendor (OpenAI, Anthropic, Zhipu, …). Pour rester air-gappé, configurez un provider Custom (compatible OpenAI) dans Settings → Models pointant vers votre relais on-prem :

• vLLM — OPENAI_API_BASE=http://vllm.internal:8000/v1 avec un OPENAI_API_KEY factice.
• Ollama — OPENAI_API_BASE=http://ollama.internal:11434/v1.
• LocalAI / LMStudio — même pattern.
• OpenRouter (on-prem) — collez l'URL de base de votre relais.

L'agent s'en moque ; le format wire compatible OpenAI est universel. Puis mettez le nouveau provider comme Default provider pour que tous les appels back-end (investigation d'alerte, translate, summarize) l'utilisent.

Voir l'entrée Custom (compatible OpenAI) sous Modèles dans la sidebar.

Base de connaissances air-gappée (sync du vault sans GitHub)

Le vault intégré sync depuis github.com/ongridio/vault au premier démarrage. Les sites air-gappés ne peuvent pas atteindre GitHub. Deux options :

Option A — livrer le vault inline

Le tarball de release inclut un snapshot de baseline du vault comme partie de l'image. Au premier démarrage, le manager le copie dans Qdrant directement — pas de réseau nécessaire. Vous obtiendrez la baseline (dernière sync entièrement publique au moment du tag de release) mais ne verrez pas les nouveaux playbooks tant que vous n'aurez pas upgradé le manager.

Option B — mirror du repo vault en interne

1. Sur un host connecté, clonez le vault public :

   git clone --bare https://github.com/ongridio/vault.git

2. Poussez vers votre serveur Git interne :

   git push --mirror git@git.internal:ops/vault.git

3. Dans Settings → Knowledge → Vault, mettez l'URL de sync à git@git.internal:ops/vault.git et collez une clé deploy SSH. Le manager utilise GIT_SSH_COMMAND pour binder la clé — voir ADR-023.

Le manager re-sync le vault à la demande depuis l'UI (bouton « Sync vault »). Chaque pull est un git fetch contre la remote configurée ; il n'y a pas de code spécifique à GitHub dans le chemin.

Upgrades, air-gappés

Comme l'install initial, pas d'internet nécessaire au moment de l'install. Le flux :

1. Sur la workstation connectée : gh release download v0.7.160 ... et vérifier le sha256.
2. Transférer le tarball.
3. Sur l'host air-gappé :

   tar xf ongrid-v0.7.160-linux-amd64.tar.xz
   cd     ongrid-v0.7.160-linux-amd64
   sudo ./upgrade.sh

4. Depuis l'UI, Edges → Upgrade all — les edges récupèrent le nouveau bundle depuis https://<manager>/edge/edge-bundle-linux-amd64-v0.7.160.tar.gz et l'appliquent via le flux stage-then-swap ADR-024 standard.

Il n'y a pas d'étape qui ait besoin d'internet au-delà de la workstation qui télécharge le tarball.

Voir upgrade pour les détails complets.

Et après

• Modèles / Custom (compatible OpenAI) — câbler un vLLM / Ollama / relais on-prem comme provider par défaut (voir Modèles dans la sidebar).
• Capacité base de connaissances — ce que contient le vault et comment ajouter vos propres runbooks.
• Plateforme on-prem — notes plus larges sur les déploiements on-prem / air-gappés incluant SELinux, CAs personnalisés, proxy sortant.