Air-Gapped-Installation

Ongrid ist darauf ausgelegt, vollständig offline zu installieren. Jedes Release-Tarball liefert:

• Das ongrid-Manager-Docker-Image,
• Das ongrid-web (Frontend + nginx) Docker-Image,
• Das singchia/frontier-Broker-Docker-Image,
• Die vier Edge-Plugin-Binaries (promtail, otelcol-contrib, node_exporter, process_exporter) für linux/amd64 und linux/arm64,
• Per-arch ongrid-edge-Binaries,
• Das optionale Offline-Embedding-Modell (fast-bge-small-zh-v1.5) für die Wissensbasis, wenn Sie make fetch-embedding-model vor make package ausgeführt haben.

Nichts wird zur Installationszeit aus Docker Hub, GitHub oder einer Vendor-API gezogen. Die einzigen externen Abhängigkeiten zur Laufzeit sind die LLM-API-Endpunkte, die Sie konfiguriert haben — für ein vollständig air-gapped Setup richten Sie diese auf ein on-prem vLLM / Ollama / OpenRouter-Relay aus.

Diese Seite deckt den Workflow für Umgebungen ab, die das öffentliche Internet nicht erreichen können.

Das Tarball auf einem verbundenen Host herunterladen

Auf einer Workstation, die Internet hat:

VER=v0.7.159

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

Sie bekommen zwei Dateien:

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

GitHub-Uploads über Clash

Große Release-Assets werden über Clash-Proxies auf halber Strecke reset. Wenn Sie herunterladen und das Tarball kurz endet, versuchen Sie es mit NO_PROXY=objects.githubusercontent.com direkt. Verifizieren Sie immer die sha256 (siehe nächster Schritt).

Die sha256 verifizieren

Bevor Sie irgendetwas anderes tun:

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

Wenn das fehlschlägt, fahren Sie nicht fort. Neu herunterladen.

Auf den Air-Gapped-Host transferieren

Welcher Weg auch immer an Ihrem Standort genehmigt ist. USB-Stick, internes Artefakt-Repo, SFTP durch eine Jumpbox. Die zwei Dateien reisen zusammen; Sie können die sha256 nach dem Transfer erneut verifizieren.

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

Installation

Dasselbe wie die Server-Installation — keine Flags für Air-Gapped erforderlich, der Installer reicht nie hinaus:

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

install.sh tut:

• docker load der drei gebündelten Images (images/ongrid.tar, images/frontier.tar, images/ongrid-web.tar).
• Konfigurationen lagern, Host-Datenverzeichnisse einrichten, das selbstsignierte TLS-Zertifikat generieren (verwendet lokales openssl; keine externe CA nötig).
• .env aus dem Template verdrahten, starke zufällige Secrets in-place generieren, nach ONGRID_PUBLIC_URL fragen.
• docker compose up -d, /healthz pollen.

Sie sollten keine „downloading..."-Log-Zeilen sehen.

Die Install-URL on-prem hosten

Wenn Edges sich selbst installieren, machen sie curl https://<manager>/install.sh | bash. Das install.sh, das sie fetchen, wird vom Manager selbst bedient — konkret von nginx aus /opt/ongrid/edge/install.sh. Es gibt keine GitHub- oder andere externe Abhängigkeit im Edge-Install-Pfad.

Dasselbe nginx bedient:

Pfad auf nginx	Was
/install.sh	Das Edge install.sh-Skript.
/edge/ongrid-edge-linux-amd64	Das Edge-Agent-Binary.
/edge/ongrid-edge-linux-arm64	Dasselbe, arm64.
/edge/promtail-linux-amd64	Plugin-Binary.
/edge/otelcol-contrib-linux-amd64	Plugin-Binary.
/edge/node_exporter-linux-amd64	Plugin-Binary.
/edge/process_exporter-linux-amd64	Plugin-Binary.
/edge/apply-pending-upgrade.sh	ADR-024 ExecStartPre-Hook.
/edge/edge-bundle-linux-amd64-<ver>.tar.gz	Upgrade-Bundle.
/edge/edge-bundle-linux-amd64-<ver>.tar.gz.sha256	Sidecar.

All das landet in /opt/ongrid/edge/, wenn install.sh läuft, und wird vom nginx-Container read-only bedient. Nichts anderes ist erforderlich.

Edge-Installation (air-gapped)

Der Standard-Einzeiler funktioniert, solange die Edge den Manager erreichen kann:

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

Wenn Sie einen Edge-Host haben, der den Manager nicht direkt erreichen kann, aber kann einen internen Artefakt-Mirror erreichen, können Sie:

1. Die /install.sh- und /edge/*-Pfade des Managers auf Ihren internen Webserver spiegeln.
2. Den Einzeiler auf die URL dieses Mirrors ausrichten.
3. Der Agent braucht immer noch --server-edge-addr und --server-http-addr, die auf den echten Manager zeigen — der Mirror hostet nur die Install-Artefakte, nicht den Tunnel.

Das ist nützlich für „die Edge kann mit dem Manager nur über TCP 40012 + eine kuratierte Menge von Ports sprechen"-Setups, wo TCP 443 zum Manager nicht verfügbar ist, aber ein Corporate-Webserver es ist.

Datenebene braucht immer noch HTTPS zum Manager

Logs und Traces pushen direkt von jeder Edge an https://<manager>/loki/api/v1/push und https://<manager>/v1/traces. Wenn Ihre Edge den Manager auf 443 nicht erreichen kann, werden diese Plugins fehlschlagen. Der Agent selbst sieht gesund aus (er braucht nur 40012), aber die Datenebene wird still sein — stellen Sie sicher, dass 443 auf dem Edge → Manager-Pfad offen ist.

Air-Gapped Model-Provider

Die Default-ONGRID_*_API_KEY=-Slots zeigen auf Vendor-URLs (OpenAI, Anthropic, Zhipu, …). Um air-gapped zu bleiben, konfigurieren Sie einen Custom (OpenAI-kompatibel)-Provider in Settings → Models, der auf Ihr on-prem-Relay zeigt:

• vLLM — OPENAI_API_BASE=http://vllm.internal:8000/v1 mit einem Dummy OPENAI_API_KEY.
• Ollama — OPENAI_API_BASE=http://ollama.internal:11434/v1.
• LocalAI / LMStudio — gleiches Muster.
• OpenRouter (on-prem) — Ihre Relay-Base-URL einfügen.

Der Agent kümmert sich nicht; das OpenAI-kompatible Wire-Format ist universell. Dann den neuen Provider als Default provider setzen, sodass alle Back-End-Aufrufe (Alarm-Untersuchung, Übersetzen, Zusammenfassen) ihn verwenden.

Siehe den Custom (OpenAI-kompatibel)-Eintrag unter Modelle in der Seitenleiste.

Air-Gapped Wissensbasis (Vault-Sync ohne GitHub)

Der eingebaute Vault synchronisiert sich beim ersten Boot von github.com/ongridio/vault. Air-Gapped-Sites können GitHub nicht erreichen. Zwei Optionen:

Option A — Vault inline ausliefern

Das Release-Tarball enthält einen Baseline-Snapshot des Vaults als Teil des Images. Beim ersten Boot kopiert der Manager ihn direkt in Qdrant — kein Netzwerk nötig. Sie bekommen die Baseline (letzter vollständig öffentlicher Sync zur Release-Tag-Zeit), sehen aber keine neuen Playbooks, bis Sie den Manager upgraden.

Option B — Das Vault-Repo intern spiegeln

1. Auf einem verbundenen Host den öffentlichen Vault klonen:

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

2. Auf Ihren internen Git-Server pushen:

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

3. In Settings → Knowledge → Vault die Sync-URL auf git@git.internal:ops/vault.git setzen und einen SSH-Deploy-Key einfügen. Der Manager verwendet GIT_SSH_COMMAND zum Binden des Schlüssels — siehe ADR-023.

Der Manager re-syncht den Vault on-Demand aus der UI (Button „Sync vault"). Jeder Pull ist ein git fetch gegen das konfigurierte Remote; es gibt keinen GitHub-spezifischen Code im Pfad.

Upgrades, air-gapped

Genauso wie die Erstinstallation, kein Internet zur Installationszeit nötig. Der Fluss:

1. Auf der verbundenen Workstation: gh release download v0.7.160 ... und sha256 verifizieren.
2. Das Tarball transferieren.
3. Auf dem Air-Gapped-Host:

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

4. Aus der UI, Edges → Upgrade all — Edges fetchen das neue Bundle von https://<manager>/edge/edge-bundle-linux-amd64-v0.7.160.tar.gz und wenden es über den Standard-ADR-024-Stage-then-Swap-Fluss an.

Es gibt keinen Schritt, der Internet jenseits der Workstation braucht, die das Tarball herunterlädt.

Siehe Upgrade für die blutigen Details.

Was als Nächstes

• Modelle / Custom (OpenAI-kompatibel) — ein vLLM / Ollama / on-prem-Relay als Default-Provider verdrahten (siehe Modelle in der Seitenleiste).
• Wissensbasis-Fähigkeit — was der Vault enthält und wie Sie Ihre eigenen Runbooks hinzufügen.
• On-Prem-Plattform — breitere Notizen zu On-Prem- / Air-Gapped-Bereitstellungen einschließlich SELinux, benutzerdefinierten CAs, ausgehendem Proxy.