Checklist de primer arranque

Justo después de que install.sh termina y has iniciado sesión como el admin bootstrap, recorre esta lista. Nada es requerido para "empezar a ver cosas" — el Quickstart funciona sin nada de esto — pero cada ítem cierra una brecha antes de que entregues el sistema a un equipo.

1. Establece ONGRID_PUBLIC_URL correctamente

Probablemente el ítem más importante. Esta URL es lo que tus edges usan para el data plane — los logs empujan a <url>/loki/api/v1/push, las trazas empujan a <url>/v1/traces.

Revisa qué rellenó install.sh:

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

Si aceptaste una dirección interna pero tus edges viven en internet público, los logs y trazas fallarán silenciosamente — el túnel sigue funcionando (tiene su propio puerto), así que el edge se ve sano.

Para arreglarlo:

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

# Restart the affected services
sudo docker compose -f /opt/ongrid/docker-compose.yml --env-file /opt/ongrid/.env up -d ongrid nginx

No necesitas re-desplegar los edges; el agente re-lee el endpoint del data plane desde el manager periódicamente.

Ver ONGRID_PUBLIC_URL.

2. Configura un provider LLM default

De fábrica, no hay provider configurado. El agente se rehusará a pensar.

1. Settings → Models. Elige uno de:
   • OpenAI (default gpt-5.4)
   • Anthropic (default claude-opus-4-7)
   • Zhipu (default glm-4.7)
   • DeepSeek (default deepseek-v4-flash)
   • Gemini (default gemini-2.5-pro)
   • Kimi (default kimi-k2.6)
   • Custom compatible con OpenAI (vLLM, Ollama, OpenRouter, relay corporativo…)
2. Pega la API key. Opcional: sobreescribe el modelo default en "Advanced".
3. Save. El pre-registro es en caliente — sin reinicio.
4. En la misma página establece Default provider al que acabas de cablear.

No mezcles default_provider y modelos por-ruta

El "default" maneja las llamadas back-end al LLM (investigación de alertas, translate, summarize). El selector de modelo en el header del chat es un override por-hilo — útil para "prueba Opus en esta única pregunta" pero el default del sitio es lo que corre para cron jobs e incidentes.

Ver las entradas Routing & default y Budget & limits bajo Modelos en la barra lateral.

3. Configura un canal de notificación

Incluso si no tienes reglas de alerta todavía, cablea un canal para que los futuros incidentes tengan donde aterrizar.

El par starter recomendado:

• Canal webhook a un collector de incoming-webhook genérico (puedes quitarlo después) — prueba que la ruta de notificación funciona.
• Un canal IM — Telegram es el más fácil porque solo necesitas un bot token y un chat ID; Slack/Lark/DingTalk/WeCom toman más setup.

Ver overview de canales.

4. Establece el timezone del manager

Los timestamps en las timelines de incidente y eventos de alerta siguen el timezone del manager. Default es UTC dentro del contenedor; para una UI que matchee tu equipo:

# Set TZ in compose env. Edit /opt/ongrid/docker-compose.yml or drop a
# /opt/ongrid/docker-compose.override.yml with:
services:
  ongrid:
    environment:
      TZ: Asia/Shanghai

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

Para el locale de salida de la IA (¿el LLM responde en inglés o chino?), setea ONGRID_DEFAULT_LOCALE. Default en; los valores válidos matchean tus traducciones de UI (en, zh-CN, ja, …). Los canales pueden sobreescribir por-canal; los requests manuales de UI siguen Accept-Language.

5. Decide la retención de Prometheus

El compose tiene default 90 días / tope 20 GB. Para cambiar:

# /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 retención de Loki edita /opt/ongrid/loki-config.yaml y reinicia el contenedor loki. Para Tempo edita /opt/ongrid/tempo-config.yaml.

6. Decide si conservar Loki / Tempo integrados

Si ya corres backends managed de log/trace (Grafana Cloud, Honeycomb, Splunk, tus propios VictoriaLogs / VictoriaTraces…), puedes:

• Conservar los embebidos como el sink de datos que el agente consulta (ruta más barata, sin infra extra).
• Cambiarlos apuntando al agente a la URL managed vía ONGRID_LOG_QUERY_URL / ONGRID_TRACE_QUERY_URL, y reconfigurando el promtail / otelcol de cada edge para empujar ahí directamente.

Para un setup híbrido (los edges empujan a ambos), deja un promtail.yaml / otelcol.yaml custom en /etc/ongrid-edge/ en cada edge y el agente lo recogerá.

Ver capacidad de logs y capacidad de trazas.

7. Sustituye el cert TLS autofirmado

Para uso de trial está bien. Para prod el cert está en /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 y upgrade.sh nunca sobreescriben certs del operador.

8. Respalda /var/lib/ongrid y /opt/ongrid/.env

Todo lo stateful vive bajo esos dos paths:

• /opt/ongrid/.env — secretos (JWT, MySQL, contraseña de admin, keys de embed).
• /var/lib/ongrid/mysql/ — todo el estado operacional. Cualquier cosa que no puedas perder vive aquí: edges, reglas de alerta, incidentes, configs de canal, audit log, skills custom, metadata de conocimiento.
• /var/lib/ongrid/qdrant/ — embeddings vectoriales (reconstruibles desde docs fuente, pero costoso).
• /var/lib/ongrid/prometheus/, loki/, tempo/ — telemetría; respalda solo si necesitas retención larga.

Un cron + rsync (o restic) simple de esas dos raíces te da recuperación ante desastres. Restore = detener el stack, sustituir los dirs, arrancar el stack.

9. Configura una cuenta de admin real

El email del admin bootstrap es lo que tú (o install.sh) pusieron en ONGRID_ADMIN_EMAIL. Para un equipo real:

1. Settings → Identity → Users → Invite user para cada operador real.
2. Asigna a cada uno un rol: admin, user, o viewer (RBAC de ADR-022).
   • admin — control total.
   • user — puede chatear con el agente, ver incidentes, silenciar alertas. Toolbag filtrado a ClassSafe.
   • viewer — chat solo lectura (sin skills de escritura), incidentes solo lectura.
3. Degrada al admin bootstrap si quieres, o simplemente deja de usarlo.

10. Dispara el primer incidente (smoke test)

Fuerza a una de las reglas integradas a disparar. La más simple: detén uno de tus edges.

sudo systemctl stop ongrid-edge

Dentro de ONGRID_ALERT_EDGE_OFFLINE_THRESHOLD (default 90s) más el intervalo del evaluator (default 5m), la regla edge_offline dispara. La UI:

• Alerts — nuevo evento.
• Incidents — nuevo agrupamiento de incidente para ese evento.
• Channels — tu canal cableado recibe una card.

Si configuraste un canal IM, responde al bot con "investigate this". El incident investigator corre end-to-end y postea de vuelta un informe.

Reinicia el edge:

sudo systemctl start ongrid-edge

El incidente se auto-mueve a mitigated cuando la regla deja de disparar; lo marcas resolved desde la UI.

Qué sigue

• Overview de canales — cablea tus canales reales de on-call.
• Capacidad de alertas — escribe reglas custom más allá de las 6 integradas.
• Upgrade — cuando v0.7.X+1 envíe.
• Reference / env — cada tunable ONGRID_*.