Quickstart

Objetivo: en unos 10 minutos tendrás…

Todo el stack de Ongrid corriendo en una única caja Linux vía docker compose (manager + broker frontier + Prometheus + Loki + Tempo + Grafana + Qdrant + SearXNG).
El usuario admin logueado sobre HTTPS.
Un ongrid-edge registrado contra tu manager, enviando métricas de CPU / memoria / disco que podrás ver en la página de Monitor.

Si quieres un recorrido más profundo, lee Instalación del servidor y Instalación del edge en su lugar.

0. Prerrequisitos

Una caja Linux (Ubuntu 22.04+, Debian 12+, RHEL/Rocky/Alma 9+ probados).

4 GB de RAM mínimo (8 GB recomendado)
20 GB libres bajo /var/lib/ongrid (el data dir)
root o sudo
docker ≥ 24 con el subcomando docker compose v2
openssl (usado para emitir el certificado TLS autofirmado en el primer arranque)
TCP 443 y 40012 abiertos hacia los hosts donde correrán tus edges

Para pruebas locales

Puedes correr todo en un portátil. Solo ten en cuenta que ONGRID_PUBLIC_URL por defecto toma la IP de LAN del portátil, así que cualquier edge que instales en otra máquina debe poder alcanzar esa IP de LAN por TCP/443.

1. Instala el servidor

La ruta de instalación canónica es gh release download más sudo ./install.sh. El tarball es autocontenido — imágenes docker, binarios de edge, archivos de configuración, todo empaquetado.

bash

# Pick the latest tag from 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

Lo que hace install.sh, en orden:

Preflight. Verifica que docker + docker compose v2 estén presentes y que el daemon sea alcanzable.
Stages config bajo /opt/ongrid/ (archivo compose, prometheus, loki, tempo, grafana, searxng, artefactos de edge).
Crea directorios de datos bajo /var/lib/ongrid/ (mysql, prometheus, loki, tempo, qdrant, grafana, embeddings) y les hace chown al uid que espera cada imagen de contenedor. Los logs van a /var/log/ongrid/.
Genera un certificado TLS autofirmado en /opt/ongrid/certs/ — los navegadores avisarán la primera vez. Sustitúyelo por un certificado real más tarde; ver Instalación del servidor.
Carga las imágenes docker (ongrid, ongrid-web, frontier) desde el tarball — sin necesidad de hacer pull desde Docker Hub.
Rellena .env con contraseñas aleatorias fuertes para MYSQL_*, ONGRID_JWT_SECRET, GRAFANA_ADMIN_PASSWORD y la contraseña bootstrap ONGRID_ADMIN_PASSWORD.
Pide ONGRID_PUBLIC_URL con cuenta atrás de 30 segundos. Esta es la URL que tus edges usarán para alcanzar el data plane de este manager (logs → Loki, trazas → OTLP push). En una terminal interactiva un valor erróneo aquí es la causa #1 de "solo el edge del host del manager envía logs", así que confírmalo. Ver ONGRID_PUBLIC_URL.
Ejecuta docker compose up -d y sondea https://localhost/healthz hasta 60 segundos.
Imprime un banner con la URL Web, la URL API, el endpoint del túnel y la contraseña bootstrap del admin — registrada una sola vez.

Una instalación sana termina así:

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.
-------------------------------------------------

Registra la contraseña del admin

La contraseña bootstrap se muestra una vez en el banner de instalación y también queda guardada (chmod 600) en /opt/ongrid/.env como ONGRID_ADMIN_PASSWORD. Si pierdes ambas tendrás que resetearla desde la base de datos; ver checklist de primer arranque.

2. Inicia sesión

Abre https://<your-host>/ en un navegador. Acepta el aviso TLS (o instala primero un certificado real). Inicia sesión con:

email — lo que hayas puesto en .env como ONGRID_ADMIN_EMAIL (por defecto admin@example.com)
password — la del banner de instalación

En el primer login aterrizas en la página de chat. El selector de modelo en la barra superior dice "no provider configured" — arregla eso antes de continuar.

3. Configura un modelo (1 min)

Ve a Settings → Models. Elige uno de:

OpenAI — pega sk-…, modelo por defecto gpt-5.4.
Anthropic — pega sk-ant-…, por defecto claude-opus-4-7.
Zhipu (GLM) — pega la API key, por defecto glm-4.7.
DeepSeek, Gemini, Kimi o Custom (compatible con OpenAI) para cualquier otro (vLLM, Ollama, OpenRouter, un relay corporativo…).

Pulsa Save. El formulario pre-registra el proveedor — sin reinicio necesario. Después, en la misma página, establece Default provider en el que acabas de configurar.

Por qué importa el default

El Default provider gobierna toda llamada LLM del back-end (investigación de alertas, translate, summarize). El selector de modelo en la página de chat solo sobreescribe para el hilo de chat actual (ver la sección Modelos en la barra lateral para detalles de routing).

Vuelve a Chat en la nav superior y pregunta "hello". Si el modelo responde, todo está conectado.

4. Registra tu primer edge

Pulsa Edges → New edge en la barra lateral. Rellena:

Name — lo que sea; p. ej. prod-web-01.
Description — opcional.

Pulsa Create. La página de detalle muestra dos cosas que necesitas:

Access key / secret key — generadas en el servidor; la secret se muestra una sola vez.
Install command — una sola línea 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

Haz SSH al host que quieres monitorizar (puede ser la misma caja en la que instalaste el manager — es una demo válida) y ejecuta ese comando como root.

Lo que sucede, en orden:

El instalador descarga el binario ongrid-edge-linux-amd64 correspondiente, más cuatro binarios de plugin (promtail, node_exporter, process_exporter, otelcol-contrib) y el hook apply-pending-upgrade.sh en /usr/local/lib/ongrid-edge/.
Crea el usuario de sistema ongrid-edge, lo hace miembro de adm y systemd-journal para que el plugin de logs pueda leer /var/log/* y el journal.
Deja una unit systemd en /etc/systemd/system/ongrid-edge.service.
Escribe /etc/ongrid-edge/ongrid-edge.env con la access/secret key (modo 0640, owner root:ongrid-edge).
systemctl enable --now ongrid-edge. Sondea el journal buscando la línea agent: registered with cloud hasta 20s.
Imprime un self-check (¿binarios de plugin presentes? ¿journald legible? ¿host del data plane alcanzable?).

Un registro exitoso termina con:

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. Míralo en la UI

De vuelta en el navegador:

Edges — tu edge está en la lista con un punto verde "online". La tarjeta muestra hostname, versión del kernel, RAM total, disco, distro.
Monitor — elige el edge. En unos ~30 segundos verás gráficas de CPU, memoria, disco, load, IO de red poblándose. Son paneles de Grafana embebidos en la página vía el sub-path /grafana/.
Logs — elige el edge. Sigue /var/log/* y el journal de systemd en vivo; LogQL soportado en la barra de búsqueda.
Topology — el edge aparece como un nodo de host. A medida que añades más edges (o detectas servicios vía el skill expand_topology), el grafo se va llenando.

6. Pregúntale al agente

Vuelve a Chat. Prueba uno de:

"List my edges and show me which has the highest load."
"Tail /var/log/syslog on prod-web-01 for the last 5 minutes."
"Why did CPU spike on prod-web-01 around 10:42?"

El agente llama a herramientas reales — list_edges, bash, query_promql, search_logs, find_topology_node, etc. La transcripción muestra cada llamada como un chip plegable; pulsa uno para ver los argumentos y la salida.

¿Qué sigue?

Configura un canal para que el agente pueda responder en Slack / Telegram / Larksuite / DingTalk / WeCom.
Crea una regla de alerta — Ongrid trae 6 reglas de host integradas y 14 kinds de regla entre PromQL / log_match / log_volume / trace_latency / trace_error_rate.
Conecta una base de conocimiento — el vault integrado es offline; añade tus propios playbooks organizacionales (Markdown, PDF, DOCX) o sincroniza un repo Git.
Endurecimiento de producción — sustituye el certificado TLS autofirmado, fija ONGRID_PUBLIC_URL con un dominio real, respalda /var/lib/ongrid, configura un default_provider real con tope de presupuesto.

Desinstalar

En el manager: cd ongrid-vX.Y.Z-linux-amd64 && sudo ./uninstall.sh. En un edge: curl -k -sSL https://<server>/install.sh | sudo bash -s -- --uninstall. Los logs bajo /var/log/ongrid-edge se preservan.

Quickstart ​

0. Prerrequisitos ​

1. Instala el servidor ​

2. Inicia sesión ​

3. Configura un modelo (1 min) ​

4. Registra tu primer edge ​

5. Míralo en la UI ​

6. Pregúntale al agente ​

¿Qué sigue? ​