Instalação air-gapped

O Ongrid é projetado para instalar totalmente offline. Cada tarball de release distribui:

• A imagem docker do manager ongrid,
• A imagem docker ongrid-web (frontend + nginx),
• A imagem docker do broker singchia/frontier,
• Os quatro binários de plugin de edge (promtail, otelcol-contrib, node_exporter, process_exporter) para linux/amd64 e linux/arm64,
• Binários ongrid-edge por arch,
• O modelo de embedding offline opcional (fast-bge-small-zh-v1.5) para a base de conhecimento se você rodou make fetch-embedding-model antes de make package.

Nada puxa do Docker Hub, GitHub, ou qualquer API de vendor no momento da instalação. As únicas dependências externas em runtime são os endpoints de API LLM que você configurou — para um setup totalmente air-gapped aponte para um relay vLLM / Ollama / OpenRouter on-prem.

Esta página cobre o workflow para ambientes que não conseguem alcançar a internet pública.

Baixe o tarball em um host conectado

Num workstation que tem internet:

VER=v0.7.159

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

Você vai pegar dois arquivos:

ongrid-v0.7.159-linux-amd64.tar.xz          # ~380 MB (compressão xz)
ongrid-v0.7.159-linux-amd64.tar.xz.sha256   # o sidecar

Uploads do GitHub via Clash

Assets grandes de release se resetam no meio do download sobre proxies Clash. Se você está baixando e o tarball termina curto, tente com NO_PROXY=objects.githubusercontent.com direto. Sempre verifique o sha256 (veja próximo passo).

Verifique o sha256

Antes de fazer qualquer outra coisa:

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

Se isso falhar, não prossiga. Re-baixe.

Transfira ao host air-gapped

Por qualquer caminho aprovado no seu site. USB key, repo interno de artefatos, SFTP por um jumpbox. Os dois arquivos viajam juntos; você pode re-verificar o sha256 após a transferência.

# No host de destino:
sha256sum -c ongrid-v0.7.159-linux-amd64.tar.xz.sha256

Instale

Igual à instalação do servidor — sem flags necessárias para air-gapped, o instalador nunca alcança o exterior:

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

install.sh faz:

• docker load das três imagens bundled (images/ongrid.tar, images/frontier.tar, images/ongrid-web.tar).
• Stage de configs, set up de data dirs no host, gera o cert TLS self-signed (usa openssl local; sem CA externa necessária).
• Wire de .env do template, gera secrets aleatórios fortes in-place, pergunta por ONGRID_PUBLIC_URL.
• docker compose up -d, polling em /healthz.

Você não deveria ver nenhuma linha de log "downloading...".

Hospedando a URL de install on-prem

Quando edges se instalam eles fazem curl https://<manager>/install.sh | bash. O install.sh que eles fetcham é servido pelo próprio manager — especificamente pelo nginx de /opt/ongrid/edge/install.sh. Não há GitHub nem outra dependência externa no caminho de install do edge.

O mesmo nginx serve:

Path no nginx	O que
/install.sh	O script install.sh do edge.
/edge/ongrid-edge-linux-amd64	O binário do edge agent.
/edge/ongrid-edge-linux-arm64	Idem, arm64.
/edge/promtail-linux-amd64	Binário do plugin.
/edge/otelcol-contrib-linux-amd64	Binário do plugin.
/edge/node_exporter-linux-amd64	Binário do plugin.
/edge/process_exporter-linux-amd64	Binário do plugin.
/edge/apply-pending-upgrade.sh	Hook ExecStartPre do ADR-024.
/edge/edge-bundle-linux-amd64-<ver>.tar.gz	Bundle de upgrade.
/edge/edge-bundle-linux-amd64-<ver>.tar.gz.sha256	Sidecar.

Todos esses pousam em /opt/ongrid/edge/ quando install.sh roda e são servidos read-only pelo container nginx. Nada mais é necessário.

Edge install (air-gapped)

O one-liner padrão funciona desde que o edge consiga alcançar o 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

Se você tem um host de edge que não consegue alcançar o manager diretamente mas consegue alcançar um mirror interno de artefatos, você pode:

1. Espelhar os paths /install.sh, /edge/* do manager no seu webserver interno.
2. Rodar o one-liner apontando para a URL desse mirror.
3. O agent ainda vai precisar de --server-edge-addr e --server-http-addr apontando para o manager real — o mirror só hospeda os artefatos de install, não o tunnel.

Isso é útil para setups "o edge consegue falar com o manager só em TCP 40012 + um conjunto curado de portas" onde TCP 443 ao manager não está disponível mas um webserver corporativo está.

Data plane ainda precisa de HTTPS ao manager

Logs e traces fazem push diretamente de cada edge para https://<manager>/loki/api/v1/push e https://<manager>/v1/traces. Se seu edge não consegue alcançar o manager em 443, esses plugins vão falhar. O próprio agent vai parecer saudável (só precisa de 40012), mas o data plane vai ficar silencioso — garanta que 443 está aberto no caminho edge → manager.

Providers de modelo air-gapped

Os slots padrão ONGRID_*_API_KEY= apontam para URLs de vendor (OpenAI, Anthropic, Zhipu, …). Para ficar air-gapped, configure um provider Custom (OpenAI-compatible) em Settings → Models apontando para seu relay on-prem:

• vLLM — OPENAI_API_BASE=http://vllm.internal:8000/v1 com um OPENAI_API_KEY dummy.
• Ollama — OPENAI_API_BASE=http://ollama.internal:11434/v1.
• LocalAI / LMStudio — mesmo padrão.
• OpenRouter (on-prem) — cole a URL base do seu relay.

O agent não se importa; o formato wire compatível com OpenAI é universal. Então defina o novo provider como Default provider para que todas as chamadas de back-end (investigação de alerta, traduzir, resumir) o usem.

Veja a entrada Custom (OpenAI-compatible) sob Modelos na sidebar.

Base de conhecimento air-gapped (sync do vault sem GitHub)

O vault built-in sincroniza de github.com/ongridio/vault no primeiro boot. Sites air-gapped não conseguem alcançar o GitHub. Duas opções:

Opção A — distribuir o vault inline

O tarball de release inclui um snapshot baseline do vault como parte da imagem. No primeiro boot o manager copia para o Qdrant diretamente — sem rede necessária. Você vai ter o baseline (último sync totalmente público no momento da release-tag) mas não vai ver novos playbooks até atualizar o manager.

Opção B — espelhar o repo do vault internamente

1. Num host conectado, clone o vault público:

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

2. Push para seu servidor Git interno:

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

3. Em Settings → Knowledge → Vault, defina a URL de sync para git@git.internal:ops/vault.git e cole uma chave SSH de deploy. O manager usa GIT_SSH_COMMAND para vincular a chave — veja ADR-023.

O manager re-sincroniza o vault sob demanda pela UI (botão "Sync vault"). Cada pull é um git fetch contra o remote configurado; não há código GitHub-específico no caminho.

Upgrades, air-gapped

Igual à instalação inicial, sem internet necessária no momento da instalação. O fluxo:

1. No workstation conectado: gh release download v0.7.160 ... e verifique sha256.
2. Transfira o tarball.
3. No host air-gapped:

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

4. Da UI, Edges → Upgrade all — edges fetcham o novo bundle de https://<manager>/edge/edge-bundle-linux-amd64-v0.7.160.tar.gz e aplicam pelo fluxo stage-then-swap padrão do ADR-024.

Não há passo que precise de internet além do workstation que baixa o tarball.

Veja upgrade para os detalhes sangrentos.

O que vem a seguir

• Modelos / Custom (OpenAI-compatible) — conectar um vLLM / Ollama / relay on-prem como provider padrão (veja Modelos na sidebar).
• Capacidade base de conhecimento — o que o vault contém e como adicionar seus próprios runbooks.
• Plataforma on-prem — notas mais amplas sobre deployments on-prem / air-gapped incluindo SELinux, CAs custom, proxy outbound.