Checklist de primeiro boot

Logo após install.sh terminar e você ter feito login como o admin de bootstrap, percorra esta lista. Nada disso é necessário para "começar a ver coisas" — o Quickstart funciona sem nenhum item — mas cada item fecha uma lacuna antes de você entregar o sistema a uma equipe.

1. Defina ONGRID_PUBLIC_URL corretamente

Provavelmente o item mais importante. Esta URL é a que seus edges usam para o data plane — logs fazem push para <url>/loki/api/v1/push, traces para <url>/v1/traces.

Cheque o que install.sh preencheu:

sudo grep '^ONGRID_PUBLIC_URL=' /opt/ongrid/.env

Se você aceitou um endereço interno mas seus edges vivem na internet pública, logs e traces vão falhar silenciosamente — o tunnel ainda funciona (tem sua própria porta), então o edge parece saudável.

Para corrigir:

# Editar
sudo sed -i 's|^ONGRID_PUBLIC_URL=.*|ONGRID_PUBLIC_URL=https://ops.example.com|' /opt/ongrid/.env

# Reiniciar os serviços afetados
sudo docker compose -f /opt/ongrid/docker-compose.yml --env-file /opt/ongrid/.env up -d ongrid nginx

Você não precisa redeployar edges; o agent relê o endpoint do data plane do manager periodicamente.

Veja ONGRID_PUBLIC_URL.

2. Configure um provider de LLM padrão

De fábrica, nenhum provider está configurado. O agent vai recusar pensar.

1. Settings → Models. Escolha um de:
   • OpenAI (padrão gpt-5.4)
   • Anthropic (padrão claude-opus-4-7)
   • Zhipu (padrão glm-4.7)
   • DeepSeek (padrão deepseek-v4-flash)
   • Gemini (padrão gemini-2.5-pro)
   • Kimi (padrão kimi-k2.6)
   • Custom OpenAI-compatible (vLLM, Ollama, OpenRouter, relay corporativo…)
2. Cole a API key. Opcional: sobrescreva o modelo padrão em "Advanced".
3. Save. Pré-registro é hot — sem restart.
4. Na mesma página defina Default provider para o que você acabou de conectar.

Não misture default_provider e modelos por rota

O "default" dirige chamadas LLM do back-end (investigação de alerta, traduzir, resumir). O picker de modelo no header do chat é um override por thread — útil para "tentar Opus nesta pergunta" mas o default do site é o que roda para cron jobs e incidentes.

Veja as entradas Routing & default e Budget & limits sob Modelos na sidebar.

3. Configure um canal de notificação

Mesmo que você não tenha rules de alerta ainda, conecte um canal para que futuros incidentes tenham onde pousar.

O par inicial recomendado:

• Canal webhook para um coletor genérico de incoming-webhook (você pode sempre remover depois) — prova que o caminho de notificação funciona.
• Um canal IM — Telegram é o mais fácil porque você só precisa de um bot token e um chat ID; Slack/Lark/DingTalk/WeCom dão mais trabalho.

Veja visão geral dos canais.

4. Defina o timezone do manager

Timestamps em timelines de incident e alert events seguem o timezone do manager. Padrão é UTC dentro do container; para uma UI que case com sua equipe:

# Defina TZ no env do compose. Edite /opt/ongrid/docker-compose.yml ou crie
# um /opt/ongrid/docker-compose.override.yml com:
services:
  ongrid:
    environment:
      TZ: Asia/Shanghai

sudo docker compose -f /opt/ongrid/docker-compose.yml --env-file /opt/ongrid/.env up -d ongrid

Para o locale de saída de IA (o LLM responde em inglês ou chinês), defina ONGRID_DEFAULT_LOCALE. Padrão en; valores válidos casam com suas traduções de UI (en, zh-CN, ja, …). Canais podem sobrescrever por canal; requisições manuais de UI seguem Accept-Language.

5. Decida a retenção do Prometheus

O compose por padrão tem 90 dias / cap de 20 GB. Para mudar:

# /opt/ongrid/docker-compose.override.yml
services:
  prometheus:
    command:
      - --storage.tsdb.path=/prometheus
      - --storage.tsdb.retention.time=30d
      - --storage.tsdb.retention.size=10GB
      - --web.enable-remote-write-receiver
      - --web.enable-lifecycle
      - --web.external-url=/prometheus/
      - --web.route-prefix=/prometheus/
      - --config.file=/etc/prometheus/prometheus.yml

sudo docker compose -f /opt/ongrid/docker-compose.yml --env-file /opt/ongrid/.env up -d prometheus

Para retenção do Loki edite /opt/ongrid/loki-config.yaml e reinicie o container loki. Para Tempo edite /opt/ongrid/tempo-config.yaml.

6. Decida se mantém Loki / Tempo built-in

Se você já roda backends gerenciados de log/trace (Grafana Cloud, Honeycomb, Splunk, seu próprio VictoriaLogs / VictoriaTraces…), você pode:

• Manter os embarcados como o data sink que o agent consulta (caminho mais barato, sem infra extra).
• Trocá-los apontando o agent para a URL gerenciada via ONGRID_LOG_QUERY_URL / ONGRID_TRACE_QUERY_URL, e reconfigurando o promtail / otelcol de cada edge para fazer push lá diretamente.

Para um setup híbrido (edges fazem push em ambos), coloque promtail.yaml / otelcol.yaml custom em /etc/ongrid-edge/ em cada edge e o agent vai pegar.

Veja capacidade de logs e capacidade de traces.

7. Substitua o cert TLS self-signed

Para uso trial está bem. Para prod o cert está em /opt/ongrid/certs/:

sudo cp fullchain.pem /opt/ongrid/certs/tls.crt
sudo cp privkey.pem   /opt/ongrid/certs/tls.key
sudo chmod 600        /opt/ongrid/certs/tls.key
sudo chmod 644        /opt/ongrid/certs/tls.crt
sudo docker compose -f /opt/ongrid/docker-compose.yml restart nginx

install.sh e upgrade.sh nunca sobrescrevem certs do operador.

8. Backup de /var/lib/ongrid e /opt/ongrid/.env

Tudo com estado vive sob esses dois paths:

• /opt/ongrid/.env — secrets (JWT, MySQL, senha admin, embed keys).
• /var/lib/ongrid/mysql/ — todo estado operacional. Tudo que você não pode perder vive aqui: edges, alert rules, incidents, configs de canal, audit log, skills custom, metadados de conhecimento.
• /var/lib/ongrid/qdrant/ — embeddings vetoriais (rebuilável de docs-fonte, mas caro).
• /var/lib/ongrid/prometheus/, loki/, tempo/ — telemetria; faça backup só se precisar de retenção longa.

Um cron + rsync (ou restic) simples desses dois roots te dá disaster recovery. Restore = pare a stack, substitua os dirs, inicie a stack.

9. Configure uma conta admin real

O email do admin de bootstrap é o que você (ou install.sh) colocou em ONGRID_ADMIN_EMAIL. Para uma equipe real:

1. Settings → Identity → Users → Invite user para cada operador real.
2. Atribua uma role a cada um: admin, user, ou viewer (RBAC do ADR-022).
   • admin — controle total.
   • user — pode chat com o agent, ver incidents, silenciar alertas. Toolbag filtrada a ClassSafe.
   • viewer — chat read-only (sem skills de write), incidents read-only.
3. Rebaixe o admin de bootstrap se quiser, ou simplesmente pare de usá-lo.

10. Dispare o primeiro incident (smoke test)

Force uma das rules built-in a disparar. Mais simples: pare um dos seus edges.

sudo systemctl stop ongrid-edge

Dentro de ONGRID_ALERT_EDGE_OFFLINE_THRESHOLD (padrão 90s) mais o intervalo do evaluator (padrão 5m), a rule edge_offline dispara. Na UI:

• Alerts — novo event.
• Incidents — novo incident agrupando esse event.
• Channels — seu canal conectado recebe um card.

Se você configurou um canal IM, responda ao bot com "investigate this". O incident investigator roda end-to-end e posta de volta um report.

Reinicie o edge:

sudo systemctl start ongrid-edge

Incident auto-move para mitigated quando a rule para de disparar; você marca como resolved pela UI.

O que vem a seguir

• Visão geral dos canais — conecte seus canais de on-call reais.
• Capacidade de alertas — escreva rules custom além das 6 built-in.
• Upgrade — quando o v0.7.X+1 sair.
• Reference / env — cada tunable ONGRID_*.