Upgrade

Dois binários para fazer upgrade: o manager (stack docker-compose) e os edges (um por host). Ambos seguem o mesmo fluxo conceitual: stage dos artefatos novos, swap atômico, fallback para a versão anterior automaticamente se a nova não subir saudável.

TL;DR

Manager:

VER=v0.7.160
gh release download "$VER" --repo ongridio/ongrid \
    -p 'ongrid-*-linux-amd64.tar.xz*'
sha256sum -c "ongrid-${VER}-linux-amd64.tar.xz.sha256"
tar xf "ongrid-${VER}-linux-amd64.tar.xz"
cd     "ongrid-${VER}-linux-amd64"
sudo ./upgrade.sh

Edges (todos, em paralelo, da UI):

• Edges → Upgrade all — manager faz push de MethodFetchPackage a cada edge conectado, cada um baixa o bundle staged de https://<manager>/edge/, faz stage, reinicia, faz swap, roda. Falhas auto-roll-back no próximo boot.

Ou para um único edge do shell:

sudo systemctl restart ongrid-edge
# O ExecStartPre roda apply-pending-upgrade.sh que pega qualquer
# bundle staged e aplica antes do novo agent iniciar.

O resto desta página explica como tudo isso de fato funciona, para você debugar quando não funciona.

Upgrade do manager: upgrade.sh

upgrade.sh vive em cada tarball de release e é para rodar dentro do tarball mais novo recém-extraído. Assume que já há uma instalação em ${ONGRID_INSTALL_DIR:-/opt/ongrid}/.

Em ordem:

1. Preflight. Verifica docker + compose v2, acha o .env existente. Aborta se não há.
2. Determina versão velha vs nova do .env existente e do arquivo VERSION do tarball novo. Loga ambas — útil para tickets de suporte.
3. docker compose down para liberar os data volumes para qualquer passo de migração.
4. Re-assert ownership de data dir sob ${ONGRID_DATA_DIR}/ (mysql, prom, loki, tempo, grafana, embeddings, qdrant). Uids de imagem não mudam há tempo mas esse é o único default seguro — re-assert é idempotente.
5. Re-stage configs do tarball novo em /opt/ongrid/: docker-compose.yml, prometheus.yml, prometheus-rules.yml, loki-config.yaml, tempo-config.yaml, grafana/, searxng/, nginx.conf, frontier.yaml, os artefatos edge/ novos, o arquivo VERSION novo. .env é preservado — upgrade.sh nunca sobrescreve env editado pelo operador.
6. Carrega imagens docker novas (ongrid.tar, ongrid-web.tar, frontier.tar se presente).
7. Bump de ONGRID_VERSION= no .env para que o próximo compose-up pegue a nova tag de imagem.
8. docker compose up -d com o env novo.
9. Polling em /healthz por 60s.
10. Banner com versão velha → nova, URL Web, comandos úteis de próximo passo.

Se algo falhar antes do passo 8, o operador pode re-rodar após consertar o problema subjacente — upgrade.sh é idempotente. Se o passo 9 falha (/healthz nunca retorna 200), os logs do manager de docker compose logs ongrid vão te dizer o que está quebrado.

Para zero-downtime, rode um setup blue/green com dois hosts de manager atrás de um load balancer; a instalação OSS single-host é breve downtime durante upgrade (~30-60s).

De onde vêm os artefatos de upgrade: make package

Esse é o caminho do operador — como você builda o tarball se você está buildando do source em vez de puxar um release. De um checkout de ongridio/ongrid:

make package

Ordem importa; isto é o que make package faz:

1. fetch-promtail — baixa promtail-<os>-<arch>.zip da release upstream do Grafana, extrai em bin/<os>-<arch>/promtail. Cacheado.
2. fetch-otelcol — idem para otelcol-contrib.
3. fetch-node-exporter — idem para node_exporter.
4. fetch-process-exporter — idem para process_exporter.
5. build-edge-all — cross-compila ongrid-edge para linux/amd64, linux/arm64, darwin/amd64, darwin/arm64.
6. docker-build — builda a imagem ongrid:<version>.
7. docker-build-broker — builda singchia/frontier:<ver> de $FRONTIER_SRC (ou pula se já está no image store local).
8. docker-build-web — builda ongrid-web:<version> (SPA frontend + nginx).
9. build-edge-bundle — monta edge-bundle-linux-amd64-<ver>.tar.gz dos binários soltos.
10. dist/package.sh — faz stage de tudo em dist/stage/ongrid-<version>-linux-amd64/, docker save das três imagens, tar.xz da coisa toda, computa o sidecar sha256, coloca em dist/out/.

A saída:

dist/out/ongrid-v0.7.160-linux-amd64.tar.xz
dist/out/ongrid-v0.7.160-linux-amd64.tar.xz.sha256

Esse é o artefato que você scp para o host prod e alimenta o ./upgrade.sh.

Modelo RAG offline

O modelo de embedding BGE não é uma dep de package — é lento de fetchar em redes CN, então fica como um passo one-off. Rode make fetch-embedding-model uma vez antes de make package se você quer que ONGRID_EMBEDDING_PROVIDER=local funcione de fábrica em um restore.

Upgrade de edge: stage-then-swap do ADR-024

O caminho do user para fazer upgrade de um edge é "clique Upgrade na UI" ou systemctl restart ongrid-edge depois que um bundle foi staged. O que realmente acontece, de cima a baixo:

1. Manager dispara, edge fetcha

Em "Upgrade all edges" (ou em um único edge):

• Manager lê dist/out/edge-bundle-<arch>-<ver>.tar.gz.sha256 de /opt/ongrid/edge/ (colocado lá por install.sh / upgrade.sh).
• Manager envia MethodFetchPackage(url=https://<manager>/edge/<bundle>, sha256=<sha>, version=<ver>) pelo tunnel aos edges alvo.
• nginx serve os bytes do bundle do mesmo dir /edge/.

2. Edge faz stage

O edge receptor:

• Baixa o bundle para /tmp/.
• Verifica o sha256 contra o manifesto que o manager mandou.
• Untar para /var/lib/ongrid-edge/.upgrade/incoming/.
• Valida cada linha <sha> <mode> <src> <dest> de MANIFEST.txt (sha bate, src existe).
• Escreve um marker "ready".
• Sai limpo. systemd reinicia a unit conforme Restart=always.

3. ExecStartPre do systemd roda o swap

A unit vem com:

ExecStartPre=-+/usr/local/lib/ongrid-edge/apply-pending-upgrade.sh
ExecStart=/usr/local/bin/ongrid-edge

O prefixo + roda o hook como root apesar de User=ongrid-edge; o - deixa um script faltante/falhando sair 0 sem bloquear a unit para que o binário pre-upgrade sempre inicie.

apply-pending-upgrade.sh faz, em ordem:

1. Modo 1: auto-rollback se um upgrade anterior rodou mas nunca escreveu healthy_marker casando com last_upgrade_ver. Restaura cada <dest>.previous sobre <dest>. Limpa o dir de staging.
2. Modo 2: apply do bundle — para cada linha de MANIFEST.txt:
   • re-verifica o sha256,
   • cp -p $dest $dest.previous (snapshot para rollback),
   • cp $src $dest.new no mesmo filesystem para que o rename final seja POSIX-atômico,
   • chmod $mode $dest.new,
   • mv -f $dest.new $dest.
3. Modo 3: apply legacy single-file para back-compat com edges que ainda não foram upgraded por bundle (só o binário do agent, sem manifesto).
4. Grava last_upgrade_at e last_upgrade_ver para o health check do próximo boot.

Então ExecStart=/usr/local/bin/ongrid-edge roda o binário recém-trocado.

4. O novo agent reporta saudável (ou não)

O novo agent, em connect bem-sucedido:

• Escreve /var/lib/ongrid-edge/.upgrade/healthy_marker com a versão que está rodando.
• Reporta register pelo tunnel com sua nova versão.

Se esse arquivo existe e casa com last_upgrade_ver pelo próximo boot, apply-pending-upgrade.sh declara sucesso, faz prune de cada .previous para liberar disco, limpa o dir de staging.

Se não (agent crashou, não consegue alcançar manager, qualquer outra coisa), o próximo boot dispara auto-rollback: cada .previous é restaurado, o dir de staging é apagado, o edge roda a versão anterior funcionando de novo. O operador vê isso na UI (o edge continua reportando uma versão "antiga" depois de um upgrade disparado — uma pista que algo está errado com o bundle novo).

Invariantes de bundle

Cada arquivo que o edge troca está no bundle; cada arquivo no bundle é um binário ou script auto-contido. Isso é não-negociável:

• O binário do agent (ongrid-edge)
• Os binários de plugin (promtail, otelcol-contrib, node_exporter, process_exporter)
• O script de hook (apply-pending-upgrade.sh)

Configs de plugin (promtail.yaml, otelcol.yaml) não estão no bundle — vivem em /etc/ongrid-edge/ e são entregues pelo tunnel como config live. Desse jeito um upgrade do agent não pisa em uma config que o operador editou à mão.

Não asse o bundle de volta na imagem docker

Se você está buildando do source, o bundle é buildado por dist/build-edge-bundle.sh no host no tempo de package, não no container. O ADR-032 impõe isso — re-assar na imagem dobra ~120 MB de bytes incompressíveis e quebra a cadeia de sha.

Onde rollbacks vivem

/usr/local/bin/ongrid-edge              # corrente
/usr/local/bin/ongrid-edge.previous     # último conhecido bom

/usr/local/lib/ongrid-edge/promtail
/usr/local/lib/ongrid-edge/promtail.previous

...etc.

/var/lib/ongrid-edge/.upgrade/
  last_upgrade_at                       # timestamp ISO
  last_upgrade_ver                      # string de versão
  healthy_marker                        # escrito pelo agent novo

Uma sequência de boot depois de um upgrade disparado:

boot 1 (pre-upgrade):
  apply-pending-upgrade.sh não vê nada staged; exit 0
  ongrid-edge v0.7.159 roda

(manager faz push do bundle, edge faz stage, edge sai limpo)

boot 2 (apply):
  apply-pending-upgrade.sh
    modo 1: sem healthy_marker ainda, mas sem last_upgrade_at também → skip
    modo 2: aplica bundle. /usr/local/bin/ongrid-edge.previous = v0.7.159
                           /usr/local/bin/ongrid-edge        = v0.7.160
            escreve last_upgrade_at, last_upgrade_ver=v0.7.160
            limpa healthy_marker
  ongrid-edge v0.7.160 roda
  v0.7.160 conecta, escreve healthy_marker=v0.7.160

(reboot, ex.: updates do host)

boot 3 (settle):
  apply-pending-upgrade.sh
    modo 1: last_upgrade_ver=v0.7.160, healthy_marker=v0.7.160 → sucesso
            prune todos os .previous
            limpa last_upgrade_at, last_upgrade_ver
  ongrid-edge v0.7.160 roda

Um cenário de falha:

boot 2 (apply):
  apply-pending-upgrade.sh: aplica bundle como acima
  ongrid-edge v0.7.160 crasha imediatamente (ex.: drift de config)
  systemd reinicia repetidamente por Restart=always

boot 3 (rollback):
  apply-pending-upgrade.sh
    modo 1: last_upgrade_ver=v0.7.160, healthy_marker faltante
            → roll back: restaura .previous sobre cada dest
              (ongrid-edge.previous → ongrid-edge, etc.)
            : > last_upgrade_at, rm -rf incoming/
  ongrid-edge v0.7.159 roda de novo (funcionando)

Downgrade

Downgrade do manager: extraia o tarball mais antigo, rode ./upgrade.sh dentro dele. Desde que nenhuma migração de schema de DB tenha rolado nas releases intermediárias, isso funciona. Cheque as release notes por qualquer aviso de "breaking schema change" antes de fazer downgrade.

Downgrade de edges: dispare um "upgrade" da UI para a versão de bundle mais antiga. A lógica do manager não se importa com a direção da versão.

O que vem a seguir

• Reference / env — nomes de env vars cujos defaults mudam entre releases.
• Instalação air-gapped — como espelhar artefatos para um webserver privado para que o apply-pending-upgrade.sh ainda consiga puxar bundles quando o próprio manager não está na internet.