Instalação do servidor (docker compose)

A instalação canônica é um tarball auto-contido e um sudo ./install.sh. O tarball distribui cada imagem docker (ongrid, ongrid-web, singchia/frontier) para que não haja pull do Docker Hub — a instalação funciona em redes restritivas e air-gapped.

Para especificidades air-gapped veja instalação air-gapped. Para um walk-through mais rápido veja Quickstart. Para a instalação systemd-native (sem docker), veja plataforma Linux server.

Pré-requisitos

Um host Linux com:

• 4 GB RAM mínimo, 8 GB recomendado (Prometheus + Loki + Tempo
  • MySQL + manager todos vivem aqui).
• 20 GB de disco livre em /var/lib/ongrid (o data root). Ajuste com ONGRID_DATA_DIR=… se quiser em outro lugar — NFS / iSCSI / NVMe todos funcionam; é um bind-mount puro.
• Docker ≥ 24 com o subcomando docker compose v2 (docker compose version deve imprimir).
• openssl — usado por install.sh para cunhar o cert TLS self-signed no primeiro boot se tls.crt / tls.key ainda não estiverem presentes.
• Inbound TCP/443 aberto do seu browser + cada edge.
• Inbound TCP/40012 aberto de cada edge (o broker frontier).
• Um IP público ou domínio que todos os edges consigam alcançar. Isso vai para ONGRID_PUBLIC_URL e é a configuração errada mais comum.

Não use IP privado para ONGRID_PUBLIC_URL

O instalador auto-detecta um IP e pede confirmação. Se você aceitar um endereço 10.x / 192.168.x / 172.16-31.x mas seus edges vivem na internet pública, logs e traces vão falhar silenciosamente em fazer push. O tunnel do control-plane ainda funciona (passa pelo nginx independentemente), então o edge parece saudável na UI — mas Loki e Tempo ficam vazios.

Instale

# 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*'

# Verifique o sha256 — o sidecar .sha256 vem com cada 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 úteis:

Flag	O que
--mode systemd	Troca para instalação nativa systemd (sem docker). Despacha para systemd/install-systemd.sh. Veja plataforma Linux server.
--with-deps	Só systemd. Auto-instala mariadb + nginx + grafana via apt/dnf, puxa binários pinados prom / loki / tempo / qdrant com verificação sha256.
--profile monitoring	Só compose. Expõe Prometheus na porta 9090 ao host (útil para dev em laptop; off por padrão em prod).
--no-seed	Só compose. Pula a saída do banner de admin-bootstrap (ao re-rodar instalação).
--force	Só compose. Reinstala em cima de uma instalação existente (preserva .env e data volume).

O que install.sh faz

Em ordem:

1. Preflight. Verifica que o CLI docker está em $PATH, o daemon é alcançável, e docker compose v2 está presente. Aborta cedo em qualquer um.

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

   • docker-compose.yml, .env.example, VERSION, frontier.yaml,
   • prometheus.yml (bind-mounted no container prom em /etc/prometheus/),
   • prometheus-rules.yml (alertas de self-observability do ADR-026),
   • loki-config.yaml, tempo-config.yaml,
   • provisionamento grafana/,
   • settings searxng/,
   • edge/ (binários de edge por arch + binários de plugin + bundle de upgrade).

3. Cria data dirs do host sob ${ONGRID_DATA_DIR:-/var/lib/ongrid}/ e faz chown para o uid que cada imagem de container roda como:

   • mysql/ → 999:999 (mysql:8.0)
   • prometheus/ → 65534:65534 (prom roda como nobody)
   • loki/ → 10001:10001
   • tempo/ → 10001:10001
   • grafana/ → 472:472
   • embeddings/ → 65532:65532 (user nonroot do manager)

   Faltar isso no primeiro boot é o que faz prom/loki/tempo/grafana quebrar com permission denied on /<datadir>.

4. Faz stage do modelo de embedding bundled para RAG offline — /var/lib/ongrid/embeddings/fast-bge-small-zh-v1.5/. Se você já trocou por um modelo custom, o instalador deixa em paz.

5. Atualiza config do nginx do tarball e, se nenhum cert estiver presente em ${INSTALL_DIR}/certs/, gera um cert self-signed válido por 365 dias (CN=ongrid, SAN: DNS:ongrid, DNS:localhost, IP:127.0.0.1).

6. Carrega imagens docker de images/ongrid.tar, images/frontier.tar, images/ongrid-web.tar via docker load. Sem pull de registry necessário.

7. Cria ou reaproveita .env. Se ${INSTALL_DIR}/.env existir, mantém (--force NÃO sobrescreve .env editado pelo operador). Senão, copia de .env.example. Então preenche espaços vazios com valores aleatórios fortes:

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

8. Pergunta por ONGRID_PUBLIC_URL se vazio. Countdown de 30 segundos, padrão = melhor palpite de host. Lê /dev/tty para sobreviver a curl ... | bash.

9. docker compose up -d com --env-file .env. Sem argumento -f, então docker-compose.override.yml auto-carrega se você tiver adicionado um para tweaks.

10. Polling em https://localhost/healthz por até 60 segundos via nginx. O /healthz do manager retorna 200 uma vez que o MySQL é alcançável e o kernel do agent está conectado.

11. Imprime o banner de instalação — URL Web, URL API, endpoint de tunnel, email + senha do admin de bootstrap (só na primeira instalação).

Depois da instalação

Você vai ver um 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.
-------------------------------------------------

Registre a senha admin

A senha de bootstrap é mostrada uma vez. Também é armazenada em /opt/ongrid/.env (mode 0600). Se você perder ambos, resete via o CLI reset-admin-password ou editando o DB direto — veja checklist de primeiro boot.

Verifique a stack

# Todos os containers devem estar Up
sudo docker compose -f /opt/ongrid/docker-compose.yml ps

# Saúde do manager
curl -fk https://localhost/healthz

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

# Acesse a UI
open https://<your-host>/   # aceite o aviso TLS

Substituindo o cert TLS

O cert self-signed está OK para trials mas todo browser vai avisar. Para produção coloque um cert real (Let's Encrypt, sua CA corp, ou o que for) 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 fornecidos pelo operador.

Wildcards funcionam

nginx serve *.crt / *.key de certs/; os únicos filenames que o container procura são tls.crt e tls.key. Symlinks estão OK se seu cert manager (certbot, acme.sh, cert-manager) mantém a cópia canônica em outro lugar.

Onde as coisas pousam

Path	Owner	Propósito
/opt/ongrid/docker-compose.yml	root	Definição do compose.
/opt/ongrid/.env	root, 0600	Secrets + tunables.
/opt/ongrid/certs/	root, 0700	tls.crt, tls.key.
/opt/ongrid/edge/	root	Binários de edge, bundle de upgrade (edge-bundle-<arch>-<ver>.tar.gz), install.sh, apply-pending-upgrade.sh. Servido read-only via nginx em /edge/.
/opt/ongrid/prometheus.yml	root	Config de scrape + remote_write do Prom.
/opt/ongrid/grafana/	root	YAMLs de provisionamento (datasources, dashboards).
/var/lib/ongrid/mysql/	999:999	Dados MySQL. Faça backup.
/var/lib/ongrid/prometheus/	65534:65534	TSDB do Prom. Retenção 90d, cap 20GB por padrão.
/var/lib/ongrid/loki/	10001:10001	Chunks + índice do Loki.
/var/lib/ongrid/tempo/	10001:10001	Blocos do Tempo.
/var/lib/ongrid/qdrant/	root	Vector store.
/var/lib/ongrid/grafana/	472:472	Estado do Grafana (dashboards, users, SA token).
/var/lib/ongrid/embeddings/	65532:65532	Cache offline do modelo BGE.
/var/log/ongrid/	misto	Arquivos de log do manager.

O que vem a seguir

• Checklist de primeiro boot — provider de modelo, retenção do Prom, URL pública, timezone, o primeiro incident.
• Instalação do edge — registre seu primeiro edge.
• Upgrade — o fluxo upgrade.sh, stage-then-swap, rollback .previous.
• Variáveis de ambiente — cada env var ONGRID_* que você pode tunar.