Instalación air-gapped

Ongrid está diseñado para instalar totalmente offline. Cada tarball de release trae:

• La imagen docker del manager ongrid,
• La imagen docker ongrid-web (frontend + nginx),
• La imagen docker del broker singchia/frontier,
• Los cuatro binarios de plugin del edge (promtail, otelcol-contrib, node_exporter, process_exporter) para linux/amd64 y linux/arm64,
• Binarios ongrid-edge por-arch,
• El modelo de embedding offline opcional (fast-bge-small-zh-v1.5) para la base de conocimiento si corriste make fetch-embedding-model antes de make package.

Nada jala de Docker Hub, GitHub o ninguna API de vendor en tiempo de instalación. Las únicas dependencias externas en runtime son los endpoints de API de LLM que hayas configurado — para una configuración totalmente air-gapped apunta esos a un relay on-prem vLLM / Ollama / OpenRouter.

Esta página cubre el workflow para entornos que no pueden alcanzar internet público.

Descarga el tarball en un host conectado

En una workstation que tenga internet:

VER=v0.7.159

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

Obtendrás dos archivos:

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

Uploads a GitHub sobre Clash

Los assets de release grandes se resetean a la mitad sobre proxies Clash. Si estás descargando y el tarball termina corto, prueba con NO_PROXY=objects.githubusercontent.com directo. Siempre verifica el sha256 (ver siguiente paso).

Verifica el sha256

Antes de hacer nada más:

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

Si esto falla, no procedas. Re-descarga.

Transfiere al host air-gapped

Cualquier ruta aprobada en tu sitio. USB key, repo interno de artefactos, SFTP a través de jumpbox. Los dos archivos viajan juntos; puedes re-verificar el sha256 después de la transferencia.

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

Instala

Lo mismo que la instalación del servidor — sin flags requeridos para air-gapped, el installer nunca sale a buscar:

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

install.sh hace:

• docker load las tres imágenes bundled (images/ongrid.tar, images/frontier.tar, images/ongrid-web.tar).
• Stage configs, configura data dirs del host, genera el cert TLS autofirmado (usa openssl local; sin CA externa necesaria).
• Cablea .env desde el template, genera secretos aleatorios fuertes in-place, pide ONGRID_PUBLIC_URL.
• docker compose up -d, sondea /healthz.

No deberías ver ninguna línea de log "downloading...".

Alojando la URL de install on-prem

Cuando los edges se instalan a sí mismos hacen curl https://<manager>/install.sh | bash. El install.sh que fetchean lo sirve el propio manager — específicamente por nginx desde /opt/ongrid/edge/install.sh. No hay dependencia externa de GitHub u otra en la ruta de install del edge.

El mismo nginx sirve:

Path en nginx	Qué
/install.sh	El script install.sh del edge.
/edge/ongrid-edge-linux-amd64	El binario del agente edge.
/edge/ongrid-edge-linux-arm64	Lo mismo, arm64.
/edge/promtail-linux-amd64	Binario de plugin.
/edge/otelcol-contrib-linux-amd64	Binario de plugin.
/edge/node_exporter-linux-amd64	Binario de plugin.
/edge/process_exporter-linux-amd64	Binario de plugin.
/edge/apply-pending-upgrade.sh	Hook ExecStartPre de ADR-024.
/edge/edge-bundle-linux-amd64-<ver>.tar.gz	Bundle de upgrade.
/edge/edge-bundle-linux-amd64-<ver>.tar.gz.sha256	Sidecar.

Todos esos aterrizan en /opt/ongrid/edge/ cuando corre install.sh y los sirve read-only el contenedor nginx. No se requiere nada más.

Instalación de edge (air-gapped)

El one-liner estándar funciona siempre que el edge pueda alcanzar al 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 tienes un host de edge que no puede alcanzar al manager directamente pero sí puede alcanzar un mirror de artefactos interno, puedes:

1. Espejar los paths /install.sh, /edge/* del manager a tu webserver interno.
2. Correr el one-liner apuntando a la URL de ese mirror.
3. El agente seguirá necesitando --server-edge-addr y --server-http-addr apuntando al manager real — el mirror solo aloja los artefactos de install, no el túnel.

Esto es útil para setups del tipo "el edge puede hablar al manager solo en TCP 40012 + un conjunto curado de puertos" donde TCP 443 al manager no está disponible pero un webserver corporativo sí.

El data plane sigue necesitando HTTPS al manager

Los logs y trazas empujan directo desde cada edge a https://<manager>/loki/api/v1/push y https://<manager>/v1/traces. Si tu edge no puede alcanzar al manager en 443, esos plugins fallarán. El agente en sí se verá sano (solo necesita 40012), pero el data plane estará silencioso — asegúrate de que 443 esté abierto en el path edge → manager.

Providers de modelo air-gapped

Los slots default ONGRID_*_API_KEY= apuntan a URLs de vendor (OpenAI, Anthropic, Zhipu, …). Para mantenerte air-gapped, configura un provider Custom (compatible con OpenAI) en Settings → Models apuntando a tu relay on-prem:

• vLLM — OPENAI_API_BASE=http://vllm.internal:8000/v1 con un dummy OPENAI_API_KEY.
• Ollama — OPENAI_API_BASE=http://ollama.internal:11434/v1.
• LocalAI / LMStudio — mismo patrón.
• OpenRouter (on-prem) — pega tu base URL del relay.

Al agente no le importa; el wire format compatible con OpenAI es universal. Luego setea el nuevo provider como Default provider para que todas las llamadas back-end (investigación de alertas, translate, summarize) lo usen.

Ver la entrada Custom (compatible con OpenAI) bajo Modelos en la barra lateral.

Base de conocimiento air-gapped (sync de vault sin GitHub)

El vault integrado se sincroniza desde github.com/ongridio/vault en el primer arranque. Los sitios air-gapped no pueden alcanzar GitHub. Dos opciones:

Opción A — distribuye el vault inline

El tarball de release incluye un snapshot baseline del vault como parte de la imagen. En el primer arranque el manager lo copia directamente a Qdrant — sin necesidad de red. Obtendrás el baseline (último sync totalmente público al tiempo de release-tag) pero no verás nuevos playbooks hasta que upgradeas el manager.

Opción B — espeja el repo de vault internamente

1. En un host conectado, clona el vault público:

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

2. Push a tu servidor Git interno:

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

3. En Settings → Knowledge → Vault, setea la URL de sync a git@git.internal:ops/vault.git y pega una SSH deploy key. El manager usa GIT_SSH_COMMAND para vincular la key — ver ADR-023.

El manager re-sincroniza el vault bajo demanda desde la UI (botón "Sync vault"). Cada pull es un git fetch contra el remote configurado; no hay código GitHub-específico en la ruta.

Upgrades, air-gapped

Como con la instalación inicial, sin internet necesaria en tiempo de install. El flujo:

1. En la workstation conectada: gh release download v0.7.160 ... y verifica sha256.
2. Transfiere el tarball.
3. En el host air-gapped:

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

4. Desde la UI, Edges → Upgrade all — los edges fetchean el nuevo bundle desde https://<manager>/edge/edge-bundle-linux-amd64-v0.7.160.tar.gz y lo aplican vía el flujo estándar stage-then-swap de ADR-024.

No hay paso que necesite internet más allá de la workstation que descarga el tarball.

Ver upgrade para los detalles sangrientos.

Qué sigue

• Models / Custom (compatible con OpenAI) — cableando un vLLM / Ollama / relay on-prem como provider default (ver Models en la barra lateral).
• Capacidad de base de conocimiento — qué contiene el vault y cómo añadir tus propios runbooks.
• Plataforma On-prem — notas más amplias sobre despliegues on-prem / air-gapped incluyendo SELinux, CAs custom, proxy saliente.