Air-gapped / on-prem

Ongrid se distribuye como un tarball autocontenido precisamente para funcionar offline. No hay apt install, sin Go-module-fetch-at-build-time en el host target, sin pull a Docker Hub en runtime. Deja el tarball, corre install.sh, y tienes un manager + flota edge funcional.

Los tradeoffs que pegarás yendo air-gapped son alrededor del provider LLM, el modelo de embedding para RAG, y los upgrades en curso. Esta página es el checklist.

Paso 1: Descarga el tarball de release

Desde un host con internet, agarra el asset de release más reciente:

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

O construye el tarball tú mismo con make package. De cualquier forma el artefacto es un único .tar.xz más su .sha256.

Mueve ambos archivos al host target vía cualquier canal air-gap que uses (USB sneakernet, servidor de artefactos interno, bucket S3 firmado, etc.).

Paso 2: Install por tarball

El tarball expande a un directorio autocontenido:

text

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

Ejecuta:

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

install.sh carga cada images/*.tar al docker local, escribe un .env razonable, levanta el stack con docker compose up -d, e imprime la URL del nuevo manager. El host necesita Docker Engine + Compose v2 — ver Linux (server).

Ver Instalación air-gapped para el paso-a-paso completo con checksums y primer boot.

Paso 3: Espejar a un registry privado (opcional)

Si tienes un registry privado de contenedores (Harbor / Artifactory / ECR / GCR), y prefieres docker pull a docker load, pushea las imágenes bundled una vez:

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

Luego escribe un docker-compose.override.yml que apunte cada servicio a registry.internal/... en vez de la imagen original, y puedes desplegar en N hosts sin re-enviar el tarball. Los upgrades futuros se convierten en "pull new image tag, docker compose up -d".

Paso 4: Install de edge en una red air-gapped

El installer curl-pipe (https://<manager>/install.sh | bash) funciona bien dentro de una red air-gapped siempre que los edges puedan alcanzar al manager (puerto 443 para el bundle estático + puerto 40012 para el túnel). El installer descarga el binario del agente y los cuatro binarios de plugin de https://<manager>/edge/, que el nginx del manager sirve desde el directorio ./bin/ bind-mounted.

Si tus edges no pueden alcanzar al manager sobre HTTPS — por ejemplo, los edges están en un segmento de red que solo permite el puerto 40012 — copia los binarios a mano:

# 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)

O, más robustamente: levanta un mirror HTTPS interno pequeño que tenga una copia de ./bin/linux-*/ y apunta un install.sh forkeado a él.

Paso 5: Provider LLM

Ongrid no bundlea un LLM. El kernel del agente llama a un provider upstream — Anthropic, OpenAI, Zhipu, DeepSeek, Gemini, Kimi o cualquier relay compatible con OpenAI — sobre la conexión saliente de internet del manager. En una red air-gapped tienes tres opciones:

Proxy saliente. Setea HTTPS_PROXY=http://your-proxy:3128 en el bloque env del manager. Todas las llamadas a provider fluyen por el proxy.
Relay compatible con OpenAI self-hosted. Corre vLLM / TGI / Ollama / one-api dentro de tu red, apunta ONGRID_OPENAI_BASE_URL a él, setea ONGRID_OPENAI_API_KEY a lo que el relay espere. Este es el patrón más común para instalaciones totalmente desconectadas.
Provider custom en la UI. Settings → Models → Custom (compatible con OpenAI) te da el mismo cableado sin reinicio.

Si quieres usar Zhipu (GLM) contra un endpoint hosteado en Tencent Cloud dentro de China, setea ONGRID_ZHIPU_BASE_URL al endpoint regional y ONGRID_ZHIPU_API_KEY a tu key — sin proxy necesario, GLM es alcanzable dentro de la red de China-continental.

Paso 6: RAG offline (el modelo de embedding)

La ingesta de base de conocimiento necesita un modelo de embedding. Por defecto el manager llama a la API de embedding de GLM (embedding-3) que necesita internet. Para un despliegue totalmente offline, cambia al perfil local embedding:

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

El tarball de release envía el modelo BAAI/bge-base-en-v1.5 bajo .cache/bge-base-en-v1.5/ (~400 MB). El install script lo copia al volumen named en el primer boot. Si te saltaste make fetch-embedding-model cuando construiste el tarball, el modelo está ausente y el embedding fallará — corre ese paso una vez y re-packagealo.

El vault integrado default de Ongrid (github.com/ongridio/vault) es público y contiene runbooks baseline distribuidos en la semilla RAG embebida. Sincronizarlo requiere alcanzar GitHub. En una red air-gapped puedes:

Vendorizar el vault a tu propio servidor Git interno y actualizar ONGRID_VAULT_REPO_URL.
O, saltarte el sync del vault totalmente — la semilla embebida (cerca de 96 playbooks) vive dentro del binario y está siempre disponible.

Paso 7: Upgrades

Dos rutas:

Mismo mecanismo de tarball. Descarga el nuevo tarball en un host con internet, sneakernet, corre ./upgrade.sh. Esto es install.sh menos el bootstrap — carga de imagen + docker compose up -d. Los agentes edge recogen los binarios de agente + plugin matcheantes la próxima vez que reconecten (staging de whole-bundle de ADR-024).
Pull a registry privado. Si espejaste las imágenes (Paso 3), docker compose pull && docker compose up -d es suficiente. Los edges todavía necesitan los nuevos binarios de agente + plugin, que fetchean del path estático /edge/ del manager — eso se actualiza automáticamente cuando swappeas el directorio bin/ distribuido por el tarball.

Qué NO funciona air-gapped

Auto-sync del vault integrado sin un mirror — el repo del vault vive en GitHub.
LLMs hosteados de provider sin un proxy saliente o relay — no hay un LLM local enviado.
El perfil default de embedding GLM — cambia a local (ver Paso 6).
Instalaciones de skills del marketplace público (ADR-017) — apunta a un registry privado en su lugar.

Todo lo demás, incluyendo el kernel del agente completo, el alert evaluator, el pipeline de telemetría y la UI de chat, corre totalmente offline.

Air-gapped / on-prem ​

Paso 1: Descarga el tarball de release ​

Paso 2: Install por tarball ​

Paso 3: Espejar a un registry privado (opcional) ​

Paso 4: Install de edge en una red air-gapped ​

Paso 5: Provider LLM ​

Paso 6: RAG offline (el modelo de embedding) ​

Paso 7: Upgrades ​

Qué NO funciona air-gapped ​