Установка сервера (docker compose)

Каноническая установка — это самодостаточный tarball и sudo ./install.sh. Tarball отгружает каждый docker-образ (ongrid, ongrid-web, singchia/frontier), так что pull из Docker Hub нет — установка работает в restrictive-сетях и air-gapped.

Для air-gapped специфики см. air-gapped установку. Для более быстрого walk-through см. Quickstart. Для systemd-native установки (без docker) см. Linux server платформу.

Prereqs

Linux-хост с:

• 4 GB RAM минимум, 8 GB рекомендуется (Prometheus + Loki + Tempo + MySQL + manager — все живут здесь).
• 20 GB свободного диска под /var/lib/ongrid (data root). Настройте с ONGRID_DATA_DIR=…, если хотите где-то ещё — NFS / iSCSI / NVMe — все работают; это простой bind-mount.
• Docker ≥ 24 с подкомандой docker compose v2 (docker compose version должна печатать).
• openssl — используется install.sh, чтобы сгенерировать self-signed TLS-сертификат при первом запуске, если tls.crt / tls.key ещё не присутствуют.
• Входящий TCP/443 открыт из вашего браузера + каждого edge.
• Входящий TCP/40012 открыт из каждого edge (frontier-брокер).
• Публичный IP или домен, до которого все edge'и могут дотянуться. Это идёт в ONGRID_PUBLIC_URL и самая частая misconfiguration.

Не используйте приватный IP для ONGRID_PUBLIC_URL

Installer автоопределяет IP и просит вас подтвердить. Если вы принимаете адрес 10.x / 192.168.x / 172.16-31.x, но ваши edge'и живут в публичном интернете, логи и трейсы будут молча падать при push. Control-plane туннель всё ещё работает (он идёт через nginx независимо), так что edge выглядит здоровым в UI — но Loki и Tempo остаются пустыми.

Установка

# 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

Полезные флаги:

Флаг	Что
--mode systemd	Переключить на нативную systemd-установку (без docker). Диспетчирует на systemd/install-systemd.sh. См. Linux server платформу.
--with-deps	Только systemd. Авто-установить mariadb + nginx + grafana через apt/dnf, pull pinned prom / loki / tempo / qdrant бинари с sha256-верификацией.
--profile monitoring	Только compose. Выставить Prometheus на порту 9090 на хост (полезно для laptop dev; выкл по умолчанию в prod).
--no-seed	Только compose. Пропустить вывод admin-bootstrap баннера (при повторном запуске установки).
--force	Только compose. Переустановить поверх существующей установки (сохраняет .env и data volume).

Что делает install.sh

По порядку:

1. Preflight. Верифицирует, что CLI docker в $PATH, daemon достижим, и docker compose v2 присутствует. Срывается рано на любом из них.

2. Stage'ит конфиги в ${ONGRID_INSTALL_DIR:-/opt/ongrid}/:

   • docker-compose.yml, .env.example, VERSION, frontier.yaml,
   • prometheus.yml (bind-mounted в prom-контейнер на /etc/prometheus/),
   • prometheus-rules.yml (ADR-026 self-observability алерты),
   • loki-config.yaml, tempo-config.yaml,
   • grafana/ provisioning,
   • searxng/ настройки,
   • edge/ (per-arch edge-бинари + plugin-бинари + upgrade- bundle).

3. Создаёт host data dirs под ${ONGRID_DATA_DIR:-/var/lib/ongrid}/ и chown'ит их на uid, под которым работает образ каждого контейнера:

   • mysql/ → 999:999 (mysql:8.0)
   • prometheus/ → 65534:65534 (prom бежит как nobody)
   • loki/ → 10001:10001
   • tempo/ → 10001:10001
   • grafana/ → 472:472
   • embeddings/ → 65532:65532 (manager nonroot user)

   Пропуск этого при первом запуске — это то, что заставляет prom/loki/tempo/grafana падать с permission denied on /<datadir>.

4. Stage'ит bundled embedding-модель для offline RAG — /var/lib/ongrid/embeddings/fast-bge-small-zh-v1.5/. Если вы уже свопнули кастомную модель, installer её оставляет.

5. Обновляет nginx-конфиг из tarball и, если сертификаты не присутствуют в ${INSTALL_DIR}/certs/, генерирует self-signed сертификат валидный 365 дней (CN=ongrid, SAN: DNS:ongrid, DNS:localhost, IP:127.0.0.1).

6. Загружает docker-образы из images/ongrid.tar, images/frontier.tar, images/ongrid-web.tar через docker load. Pull из registry не требуется.

7. Создаёт или переиспользует .env. Если ${INSTALL_DIR}/.env существует, оставляет его (--force НЕ перезаписывает operator-edited .env). Если нет, копирует из .env.example. Затем заполняет пробелы сильными случайными значениями:

   • MYSQL_ROOT_PASSWORD, MYSQL_PASSWORD — 24 символа,
   • ONGRID_JWT_SECRET — 64 символа,
   • ONGRID_ADMIN_PASSWORD — 20 символов (записан для финального баннера),
   • GRAFANA_ADMIN_PASSWORD — 20 символов.

8. Просит ONGRID_PUBLIC_URL, если пусто. 30-секундный countdown, default = best-guess host. Читает /dev/tty, так что переживает curl ... | bash.

9. docker compose up -d с --env-file .env. Без -f аргумента, так что docker-compose.override.yml авто-загружается, если вы добавили один для tweaks.

10. Polls https://localhost/healthz до 60 секунд через nginx. /healthz manager'а возвращает 200, как только MySQL достижим и agent kernel подключён.

11. Печатает install-баннер — Web URL, API URL, tunnel endpoint, bootstrap admin email + password (только при первой установке).

После установки

Вы увидите баннер вроде:

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

Запишите admin-пароль

Bootstrap-пароль показывается один раз. Он также хранится в /opt/ongrid/.env (mode 0600). Если вы потеряете оба, ресетьте через CLI reset-admin-password или редактируя БД напрямую — см. чек-лист первого запуска.

Верификация стека

# 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

Замена TLS-сертификата

Self-signed сертификат нормален для пробного использования, но каждый браузер предупредит. Для production положите реальный сертификат (Let's Encrypt, ваш corp CA или что угодно) в /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 и upgrade.sh никогда не перезаписывают operator-provided сертификаты.

Wildcards работают

nginx сервит *.crt / *.key из certs/; единственные имена файлов, которые контейнер ищет, — это tls.crt и tls.key. Symlinks — нормально, если ваш cert manager (certbot, acme.sh, cert-manager) держит каноническую копию в другом месте.

Куда что приземляется

Путь	Owner	Назначение
/opt/ongrid/docker-compose.yml	root	Compose-определение.
/opt/ongrid/.env	root, 0600	Секреты + tunables.
/opt/ongrid/certs/	root, 0700	tls.crt, tls.key.
/opt/ongrid/edge/	root	Edge-бинари, upgrade-bundle (edge-bundle-<arch>-<ver>.tar.gz), install.sh, apply-pending-upgrade.sh. Сервится read-only через nginx на /edge/.
/opt/ongrid/prometheus.yml	root	Prom scrape + remote_write конфиг.
/opt/ongrid/grafana/	root	Provisioning yaml'ы (datasources, dashboards).
/var/lib/ongrid/mysql/	999:999	MySQL data. Бэкапьте это.
/var/lib/ongrid/prometheus/	65534:65534	Prom TSDB. 90d retention, 20GB cap по умолчанию.
/var/lib/ongrid/loki/	10001:10001	Loki chunks + index.
/var/lib/ongrid/tempo/	10001:10001	Tempo blocks.
/var/lib/ongrid/qdrant/	root	Vector store.
/var/lib/ongrid/grafana/	472:472	Grafana state (dashboards, users, SA token).
/var/lib/ongrid/embeddings/	65532:65532	Offline BGE model cache.
/var/log/ongrid/	mixed	Manager log-файлы.

Что дальше

• Чек-лист первого запуска — model provider, Prom retention, public URL, timezone, первый incident.
• Установка edge — зарегистрируйте первый edge.
• Апгрейд — flow upgrade.sh, stage-then-swap, .previous rollback.
• Переменные окружения — каждая ONGRID_* env- переменная, которую можно настроить.