Instalación del servidor (docker compose)

La instalación canónica es un tarball autocontenido y un sudo ./install.sh. El tarball trae cada imagen docker (ongrid, ongrid-web, singchia/frontier) así que no hay pull de Docker Hub — la instalación funciona en redes restrictivas y air-gapped.

Para specifics air-gapped ver instalación air-gapped. Para un recorrido más rápido ver Quickstart. Para la instalación systemd-native (sin docker), ver plataforma Linux server.

Prereqs

Un host Linux con:

• 4 GB de RAM mínimo, 8 GB recomendado (Prometheus + Loki + Tempo + MySQL + manager viven todos aquí).
• 20 GB libres en disco bajo /var/lib/ongrid (la raíz de datos). Ajusta con ONGRID_DATA_DIR=… si la quieres en otro lado — NFS / iSCSI / NVMe todos funcionan; es un bind-mount plano.
• Docker ≥ 24 con el subcomando docker compose v2 (docker compose version debería imprimir).
• openssl — usado por install.sh para emitir el certificado TLS autofirmado en el primer arranque si tls.crt / tls.key no están presentes.
• TCP/443 entrante abierto desde tu navegador + cada edge.
• TCP/40012 entrante abierto desde cada edge (el broker frontier).
• Una IP pública o dominio que cada edge pueda alcanzar. Esto va en ONGRID_PUBLIC_URL y es la mala configuración más común.

No uses una IP privada para ONGRID_PUBLIC_URL

El instalador auto-detecta una IP y te pide confirmar. Si aceptas una dirección 10.x / 192.168.x / 172.16-31.x pero tus edges viven en internet público, los logs y trazas fallarán silenciosamente al empujar. El túnel del control plane sigue funcionando (va por nginx independientemente), así que el edge se ve sano en la UI — pero Loki y Tempo se quedan vacíos.

Instala

# Pick the latest tag at https://github.com/ongridio/ongrid/releases
VER=v0.7.159

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

# Verify the sha256 — the .sha256 sidecar ships with each release.
sha256sum -c "ongrid-${VER}-linux-amd64.tar.xz.sha256"

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

sudo ./install.sh

Flags útiles:

Flag	Qué
--mode systemd	Cambia a instalación native systemd (sin docker). Despacha a systemd/install-systemd.sh. Ver plataforma Linux server.
--with-deps	Solo systemd. Auto-instala mariadb + nginx + grafana vía apt/dnf, jala binarios pinned prom / loki / tempo / qdrant con verify sha256.
--profile monitoring	Solo compose. Expone Prometheus en el puerto 9090 al host (útil para dev de laptop; off por defecto en prod).
--no-seed	Solo compose. Salta la salida del banner de admin-bootstrap (cuando se re-ejecuta una instalación).
--force	Solo compose. Reinstala sobre una instalación existente (preserva .env y el volumen de datos).

Qué hace install.sh

En orden:

1. Preflight. Verifica que la CLI de docker esté en $PATH, el daemon sea alcanzable y docker compose v2 esté presente. Aborta temprano ante cualquiera.

2. Stage configs en ${ONGRID_INSTALL_DIR:-/opt/ongrid}/:

   • docker-compose.yml, .env.example, VERSION, frontier.yaml,
   • prometheus.yml (bind-mounted al contenedor prom en /etc/prometheus/),
   • prometheus-rules.yml (alertas de self-observability de ADR-026),
   • loki-config.yaml, tempo-config.yaml,
   • provisioning de grafana/,
   • settings de searxng/,
   • edge/ (binarios edge por-arch + binarios de plugin + bundle de upgrade).

3. Crea data dirs del host bajo ${ONGRID_DATA_DIR:-/var/lib/ongrid}/ y les hace chown al uid con el que corre la imagen de cada contenedor:

   • mysql/ → 999:999 (mysql:8.0)
   • prometheus/ → 65534:65534 (prom corre como nobody)
   • loki/ → 10001:10001
   • tempo/ → 10001:10001
   • grafana/ → 472:472
   • embeddings/ → 65532:65532 (usuario nonroot del manager)

   Faltar esto en el primer arranque es lo que hace que prom/loki/tempo/grafana crasheen con permission denied on /<datadir>.

4. Stagea el modelo de embedding bundled para RAG offline — /var/lib/ongrid/embeddings/fast-bge-small-zh-v1.5/. Si ya cambiaste a un modelo custom el instalador lo deja en paz.

5. Refresca config de nginx del tarball y, si no hay certs presentes en ${INSTALL_DIR}/certs/, genera un cert autofirmado válido 365 días (CN=ongrid, SAN: DNS:ongrid, DNS:localhost, IP:127.0.0.1).

6. Carga imágenes docker desde images/ongrid.tar, images/frontier.tar, images/ongrid-web.tar vía docker load. Sin pull a registry requerido.

7. Crea o reutiliza .env. Si ${INSTALL_DIR}/.env existe, lo conserva (--force NO sobrescribe .env editado por el operador). Si no, copia de .env.example. Luego rellena los blanks con valores aleatorios fuertes:

   • MYSQL_ROOT_PASSWORD, MYSQL_PASSWORD — 24 chars,
   • ONGRID_JWT_SECRET — 64 chars,
   • ONGRID_ADMIN_PASSWORD — 20 chars (grabado para el banner final),
   • GRAFANA_ADMIN_PASSWORD — 20 chars.

8. Pide ONGRID_PUBLIC_URL si está en blanco. Cuenta atrás de 30 segundos, default = mejor guess de host. Lee /dev/tty para que sobreviva a curl ... | bash.

9. docker compose up -d con --env-file .env. Sin argumento -f, así que docker-compose.override.yml se auto-carga si has añadido uno para tweaks.

10. Sondea https://localhost/healthz hasta 60 segundos vía nginx. El /healthz del manager devuelve 200 una vez que MySQL es alcanzable y el kernel del agente está cableado.

11. Imprime el banner de instalación — URL Web, URL API, endpoint del túnel, email + password de admin bootstrap (solo en la primera instalación).

Después de instalar

Verás un banner como:

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

Install dir:     /opt/ongrid
Version:         v0.7.159

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)

TLS: self-signed cert in /opt/ongrid/certs/ — browsers will warn
      on first visit. Replace tls.crt + tls.key with a real cert and
      'docker compose -f /opt/ongrid/docker-compose.yml restart nginx'.

---------------- 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 sola vez. También queda guardada en /opt/ongrid/.env (modo 0600). Si pierdes ambas, resetea vía la CLI reset-admin-password o editando la DB directamente — ver checklist de primer arranque.

Verifica el stack

# All containers should be Up
sudo docker compose -f /opt/ongrid/docker-compose.yml ps

# Manager health
curl -fk https://localhost/healthz

# Tail manager logs
sudo docker compose -f /opt/ongrid/docker-compose.yml logs -f ongrid

# Browse to the UI
open https://<your-host>/   # accept the TLS warning

Sustituyendo el certificado TLS

El cert autofirmado está bien para trials pero cada navegador advertirá. Para prod deja un cert real (Let's Encrypt, tu CA corp, o lo que sea) 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 provistos por el operador.

Los wildcards funcionan

nginx sirve *.crt / *.key desde certs/; los únicos nombres de archivo que el contenedor busca son tls.crt y tls.key. Los symlinks están bien si tu cert manager (certbot, acme.sh, cert-manager) mantiene la copia canónica en otro lado.

Dónde aterrizan las cosas

Ruta	Owner	Propósito
/opt/ongrid/docker-compose.yml	root	Definición de compose.
/opt/ongrid/.env	root, 0600	Secretos + tunables.
/opt/ongrid/certs/	root, 0700	tls.crt, tls.key.
/opt/ongrid/edge/	root	Binarios de edge, bundle de upgrade (edge-bundle-<arch>-<ver>.tar.gz), install.sh, apply-pending-upgrade.sh. Servido read-only vía nginx en /edge/.
/opt/ongrid/prometheus.yml	root	Config scrape + remote_write de Prom.
/opt/ongrid/grafana/	root	YAMLs de provisioning (datasources, dashboards).
/var/lib/ongrid/mysql/	999:999	Data de MySQL. Respáldala.
/var/lib/ongrid/prometheus/	65534:65534	TSDB de Prom. Retención 90d, tope 20GB por defecto.
/var/lib/ongrid/loki/	10001:10001	Chunks + index de Loki.
/var/lib/ongrid/tempo/	10001:10001	Bloques de Tempo.
/var/lib/ongrid/qdrant/	root	Vector store.
/var/lib/ongrid/grafana/	472:472	Estado de Grafana (dashboards, usuarios, SA token).
/var/lib/ongrid/embeddings/	65532:65532	Cache del modelo BGE offline.
/var/log/ongrid/	mixto	Archivos de log del manager.

Qué sigue

• Checklist de primer arranque — provider de modelo, retención de Prom, URL pública, timezone, el primer incidente.
• Instalación de edge — registra tu primer edge.
• Upgrade — el flujo upgrade.sh, stage-then-swap, rollback con .previous.
• Variables de entorno — cada variable ONGRID_* que puedes afinar.