Quickstart

Objetivo: em cerca de 10 minutos você terá…

A stack Ongrid completa rodando em uma única caixa Linux via docker compose (manager + frontier broker + Prometheus + Loki + Tempo + Grafana + Qdrant + SearXNG).
O usuário admin logado por HTTPS.
Um ongrid-edge registrado contra seu manager, enviando métricas de CPU / memória / disco que você consegue ver na página Monitor.

Se você quer um walk-through mais profundo, leia Instalação do servidor e Instalação do edge em vez disso.

0. Pré-requisitos

Uma caixa Linux (Ubuntu 22.04+, Debian 12+, RHEL/Rocky/Alma 9+ testados).

4 GB de RAM mínimo (8 GB recomendado)
20 GB livres em /var/lib/ongrid (o data dir)
root ou sudo
docker ≥ 24 com o subcomando docker compose v2
openssl (usado para cunhar o certificado TLS self-signed no primeiro boot)
TCP 443 e 40012 abertos para os hosts onde seus edges rodarão

Para teste local apenas

Você pode rodar tudo num laptop. Só lembre que ONGRID_PUBLIC_URL por padrão é o IP LAN do laptop, então qualquer edge que você instale em outra máquina precisa conseguir alcançar esse IP LAN em TCP/443.

1. Instale o servidor

O caminho de instalação canônico é gh release download mais sudo ./install.sh. O tarball é auto-contido — imagens docker, binários de edge, arquivos de config, tudo empacotado.

bash

# Escolha a última tag em https://github.com/ongridio/ongrid/releases
VER=v0.7.159

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

tar xf "ongrid-${VER}-linux-amd64.tar.xz"
cd     "ongrid-${VER}-linux-amd64"

sudo ./install.sh

O que install.sh faz, em ordem:

Preflight. Verifica que docker + docker compose v2 estão presentes e que o daemon é alcançável.
Faz stage da config sob /opt/ongrid/ (compose file, prometheus, loki, tempo, grafana, searxng, artefatos de edge).
Cria data dirs sob /var/lib/ongrid/ (mysql, prometheus, loki, tempo, qdrant, grafana, embeddings) e faz chown delas para o uid que cada imagem de container espera. Logs vão para /var/log/ongrid/.
Gera um cert TLS self-signed em /opt/ongrid/certs/ — browsers vão avisar da primeira vez. Substitua por um cert real depois; veja Instalação do servidor.
Carrega imagens docker (ongrid, ongrid-web, frontier) do tarball — sem pull do Docker Hub necessário.
Preenche .env com senhas aleatórias fortes para MYSQL_*, ONGRID_JWT_SECRET, GRAFANA_ADMIN_PASSWORD, e a senha admin de bootstrap ONGRID_ADMIN_PASSWORD.
Pergunta ONGRID_PUBLIC_URL com um countdown de 30 segundos. Essa é a URL que seus edges vão usar para alcançar o data plane deste manager (logs → Loki, traces → push OTLP). Num terminal interativo um valor errado aqui é a #1 causa de "só o edge no host do manager envia logs", então confirme. Veja ONGRID_PUBLIC_URL.
Roda docker compose up -d e faz polling em https://localhost/healthz por até 60 segundos.
Imprime um banner com a URL Web, URL API, endpoint de tunnel, e a senha de admin de bootstrap — registrada uma vez.

Uma instalação saudável termina assim:

text

[INFO] ongrid is healthy (took ~14s)

===============================================================
  ongrid installation complete
===============================================================

Web UI:          https://203.0.113.10/
API URL:         https://203.0.113.10/api/v1
Tunnel endpoint: 203.0.113.10:40012   (for edges)

---------------- bootstrap admin ----------------
email:    admin@example.com
password: 9Xp4hKqf1bL2zRq3Wn7v
>> Record this password NOW. It will not be shown again.
-------------------------------------------------

Registre a senha admin

A senha de bootstrap é mostrada uma vez no banner de instalação e também armazenada (chmod 600) em /opt/ongrid/.env como ONGRID_ADMIN_PASSWORD. Se você perder ambos, vai precisar resetar do banco; veja checklist de primeiro boot.

Abra https://<seu-host>/ em um browser. Aceite o aviso TLS (ou instale um cert real primeiro). Faça login com:

email — o que você colocou em .env como ONGRID_ADMIN_EMAIL (padrão admin@example.com)
senha — a do banner de instalação

No primeiro login você cai na home page de chat. O picker de modelo no top bar diz "no provider configured" — conserte isso antes de continuar.

3. Configure um modelo (1 min)

Vá para Settings → Models. Escolha qualquer um de:

OpenAI — cole sk-…, modelo padrão gpt-5.4.
Anthropic — cole sk-ant-…, padrão claude-opus-4-7.
Zhipu (GLM) — cole API key, padrão glm-4.7.
DeepSeek, Gemini, Kimi, ou Custom (OpenAI-compatible) para qualquer outro (vLLM, Ollama, OpenRouter, um relay corporativo…).

Pressione Save. O form pré-registra o provider — sem restart necessário. Então na mesma página defina Default provider para o que você acabou de configurar.

Por que o default importa

O Default provider dirige cada chamada LLM do back-end (investigação de alerta, traduzir, resumir). O picker de modelo na página de chat só sobrescreve para a thread de chat atual (veja a seção Modelos na sidebar para detalhes de roteamento).

Volte para Chat na nav top e pergunte "hello". Se o modelo responder, está conectado.

4. Registre seu primeiro edge

Clique em Edges → New edge na nav lateral. Preencha:

Name — qualquer coisa; ex.: prod-web-01.
Description — opcional.

Pressione Create. A página de detalhe mostra duas coisas que você precisa:

Access key / secret key — geradas server-side; a secret é mostrada uma vez.
Comando de install — uma única linha como:

bash

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

SSH ao host que você quer monitorar (pode ser a mesma caixa onde você instalou o manager — é uma demo válida) e rode esse comando como root.

O que acontece, em ordem:

O instalador baixa o binário ongrid-edge-linux-amd64 correspondente, mais quatro binários de plugin (promtail, node_exporter, process_exporter, otelcol-contrib) e o hook apply-pending-upgrade.sh em /usr/local/lib/ongrid-edge/.
Cria o user de sistema ongrid-edge, o torna membro de adm e systemd-journal para que o plugin de logs possa ler /var/log/* e o journal.
Drop de uma unit systemd em /etc/systemd/system/ongrid-edge.service.
Escreve /etc/ongrid-edge/ongrid-edge.env com access/secret key (mode 0640, owned root:ongrid-edge).
systemctl enable --now ongrid-edge. Faz polling no journal por a linha agent: registered with cloud por até 20s.
Imprime um self-check (binários de plugin presentes? journald legível? host de data-plane alcançável?).

Um registro bem-sucedido termina com:

text

[OK]    plugin binary present: promtail
[OK]    plugin binary present: otelcol-contrib
[OK]    plugin binary present: node_exporter
[OK]    plugin binary present: process_exporter
[OK]    journald readable by ongrid-edge
[OK]    data-plane host 203.0.113.10:443 reachable (TCP)
[OK]    self-check passed

[OK]    installed:    ongrid-edge v0.7.159
[OK]    connected:    edge_id=42 via 203.0.113.10:40012
[OK]    tail logs:    journalctl -u ongrid-edge -f

5. Veja na UI

De volta no browser:

Edges — seu edge está na lista com um ponto verde "online". O card mostra hostname, versão do kernel, RAM total, disco, distro.
Monitor — escolha o edge. Em ~30 segundos você verá gráficos de CPU, memória, disco, load, IO de rede populando. São painéis Grafana embarcados na página pelo sub-path /grafana/.
Logs — escolha o edge. Faça tail de /var/log/* e do journal systemd ao vivo; LogQL suportado na search bar.
Topologia — o edge aparece como um nó de host. Conforme você adiciona mais edges (ou detecta serviços via a skill expand_topology), o grafo se preenche.

6. Pergunte ao agent

Volte para Chat. Tente um de:

"Liste meus edges e mostre qual tem o load mais alto."
"Faça tail de /var/log/syslog em prod-web-01 nos últimos 5 minutos."
"Por que a CPU disparou em prod-web-01 em torno de 10:42?"

O agent chama tools reais — list_edges, bash, query_promql, search_logs, find_topology_node, etc. O transcript mostra cada chamada como um chip colapsível; clique em um para ver argumentos e saída.

E depois?

Configure um canal para que o agent possa responder no Slack / Telegram / Larksuite / DingTalk / WeCom.
Escreva uma alert rule — o Ongrid distribui 6 rules de host built-in e 14 kinds de rule por PromQL / log_match / log_volume / trace_latency / trace_error_rate.
Conecte uma base de conhecimento — o vault built-in é offline; adicione playbooks da sua org (Markdown, PDF, DOCX) ou sincronize um repo Git.
Hardening de produção — substitua o cert TLS self-signed, defina ONGRID_PUBLIC_URL para um domínio real, faça backup de /var/lib/ongrid, configure um default_provider real com um cap de budget.

Desinstalar

No manager: cd ongrid-vX.Y.Z-linux-amd64 && sudo ./uninstall.sh. Em um edge: curl -k -sSL https://<server>/install.sh | sudo bash -s -- --uninstall. Logs sob /var/log/ongrid-edge são preservados.

Quickstart ​

0. Pré-requisitos ​

1. Instale o servidor ​

2. Faça login ​

3. Configure um modelo (1 min) ​

4. Registre seu primeiro edge ​

5. Veja na UI ​

6. Pergunte ao agent ​

E depois? ​