Installation serveur (docker compose)

L'install canonique est un tarball auto-contenu et un sudo ./install.sh. Le tarball livre chaque image docker (ongrid, ongrid-web, singchia/frontier) donc pas de pull Docker Hub — l'install marche dans les réseaux restrictifs et air-gappés.

Pour les spécificités air-gappées, voir installation air-gappée. Pour un walk-through plus rapide, voir Démarrage rapide. Pour l'install systemd-native (pas de docker), voir Plateforme serveur Linux.

Prérequis

Un host Linux avec :

• 4 Go de RAM minimum, 8 Go recommandés (Prometheus + Loki + Tempo + MySQL + manager vivent tous ici).
• 20 Go de disque libre sous /var/lib/ongrid (la racine des données). Ajustez avec ONGRID_DATA_DIR=… si vous le voulez ailleurs — NFS / iSCSI / NVMe fonctionnent tous ; c'est un bind-mount simple.
• Docker ≥ 24 avec la sous-commande docker compose v2 (docker compose version devrait afficher).
• openssl — utilisé par install.sh pour fabriquer le cert TLS auto-signé au premier démarrage si tls.crt / tls.key ne sont pas déjà présents.
• TCP/443 entrant ouvert depuis votre navigateur + chaque edge.
• TCP/40012 entrant ouvert depuis chaque edge (le broker frontier).
• Une IP publique ou domaine que tous les edges peuvent atteindre. Cela va dans ONGRID_PUBLIC_URL et c'est la mauvaise configuration la plus courante.

N'utilisez pas une IP privée pour ONGRID_PUBLIC_URL

L'installer auto-détecte une IP et vous demande de confirmer. Si vous acceptez une adresse 10.x / 192.168.x / 172.16-31.x mais que vos edges vivent sur l'internet public, les logs et traces échoueront silencieusement à pousser. Le tunnel de plan de contrôle marche encore (il passe par nginx indépendamment), donc l'edge paraît sain dans l'UI — mais Loki et Tempo restent vides.

Installer

# 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 utiles :

Flag	Quoi
--mode systemd	Bascule vers l'install systemd-native (pas de docker). Dispatche vers systemd/install-systemd.sh. Voir Plateforme serveur Linux.
--with-deps	systemd-only. Auto-installe mariadb + nginx + grafana via apt/dnf, tire les binaires prom / loki / tempo / qdrant épinglés avec vérification sha256.
--profile monitoring	compose-only. Expose Prometheus sur le port 9090 vers l'host (utile pour le dev laptop ; off par défaut en prod).
--no-seed	compose-only. Saute l'affichage de bannière de bootstrap admin (en re-exécutant un install).
--force	compose-only. Réinstalle sur une install existante (préserve .env et le volume de données).

Ce que install.sh fait

Dans l'ordre :

1. Preflight. Vérifie que le CLI docker est dans $PATH, que le daemon est joignable, et que docker compose v2 est présent. Bail tôt sur chacun.

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

   • docker-compose.yml, .env.example, VERSION, frontier.yaml,
   • prometheus.yml (bind-mounté dans le conteneur prom à /etc/prometheus/),
   • prometheus-rules.yml (alertes d'auto-observabilité ADR-026),
   • loki-config.yaml, tempo-config.yaml,
   • provisioning grafana/,
   • settings searxng/,
   • edge/ (binaires edge par arch + binaires de plugin + bundle d'upgrade).

3. Crée les dirs de données host sous ${ONGRID_DATA_DIR:-/var/lib/ongrid}/ et les chown vers l'uid sous lequel l'image de chaque conteneur tourne :

   • mysql/ → 999:999 (mysql:8.0)
   • prometheus/ → 65534:65534 (prom tourne comme nobody)
   • loki/ → 10001:10001
   • tempo/ → 10001:10001
   • grafana/ → 472:472
   • embeddings/ → 65532:65532 (utilisateur nonroot manager)

   Manquer ceci au premier démarrage est ce qui fait crasher prom/loki/tempo/grafana avec permission denied on /<datadir>.

4. Stage le modèle d'embedding embarqué pour le RAG offline — /var/lib/ongrid/embeddings/fast-bge-small-zh-v1.5/. Si vous avez déjà swappé un modèle personnalisé, l'installer le laisse tranquille.

5. Refresh la config nginx depuis le tarball et, si aucun cert n'est présent dans ${INSTALL_DIR}/certs/, génère un cert auto-signé valide 365 jours (CN=ongrid, SAN : DNS:ongrid, DNS:localhost, IP:127.0.0.1).

6. Charge les images docker depuis images/ongrid.tar, images/frontier.tar, images/ongrid-web.tar via docker load. Pas de pull de registry requis.

7. Crée ou réutilise .env. Si ${INSTALL_DIR}/.env existe, garde-le (--force n'écrase PAS un .env édité par l'opérateur). Sinon, copie depuis .env.example. Puis remplit les blancs avec des valeurs aléatoires fortes :

   • MYSQL_ROOT_PASSWORD, MYSQL_PASSWORD — 24 chars,
   • ONGRID_JWT_SECRET — 64 chars,
   • ONGRID_ADMIN_PASSWORD — 20 chars (enregistré pour la bannière finale),
   • GRAFANA_ADMIN_PASSWORD — 20 chars.

8. Demande ONGRID_PUBLIC_URL si vide. Compte à rebours de 30 secondes, défaut = meilleure devine host. Lit /dev/tty pour survivre à curl ... | bash.

9. docker compose up -d avec --env-file .env. Pas d'argument -f, donc docker-compose.override.yml auto-charge si vous en avez ajouté un pour des ajustements.

10. Sonde https://localhost/healthz pendant jusqu'à 60 secondes via nginx. Le /healthz du manager renvoie 200 une fois que MySQL est joignable et que le kernel d'agent est câblé.

11. Affiche la bannière d'install — URL Web, URL API, endpoint du tunnel, email + mot de passe admin bootstrap (seulement au premier install).

Après l'install

Vous verrez une bannière comme :

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

Enregistrez le mot de passe admin

Le mot de passe bootstrap est affiché une fois. Il est aussi stocké dans /opt/ongrid/.env (mode 0600). Si vous perdez les deux, reset via le CLI reset-admin-password ou en éditant directement la DB — voir check-list du premier démarrage.

Vérifier la 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

Remplacement du cert TLS

Le cert auto-signé est OK pour les essais mais chaque navigateur avertira. Pour la production, déposez un vrai cert (Let's Encrypt, votre CA corp, ou autre) dans /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 et upgrade.sh n'écrasent jamais les certs fournis par l'opérateur.

Les wildcards fonctionnent

nginx sert *.crt / *.key depuis certs/ ; les seuls noms de fichiers que le conteneur cherche sont tls.crt et tls.key. Les symlinks vont bien si votre gestionnaire de cert (certbot, acme.sh, cert-manager) garde la copie canonique ailleurs.

Où les choses atterrissent

Chemin	Owner	Rôle
/opt/ongrid/docker-compose.yml	root	Définition compose.
/opt/ongrid/.env	root, 0600	Secrets + ajustables.
/opt/ongrid/certs/	root, 0700	tls.crt, tls.key.
/opt/ongrid/edge/	root	Binaires edge, bundle d'upgrade (edge-bundle-<arch>-<ver>.tar.gz), install.sh, apply-pending-upgrade.sh. Servis en lecture seule via nginx à /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	Données MySQL. Sauvegardez ça.
/var/lib/ongrid/prometheus/	65534:65534	TSDB Prom. Rétention 90j, plafond 20Go par défaut.
/var/lib/ongrid/loki/	10001:10001	Chunks + index Loki.
/var/lib/ongrid/tempo/	10001:10001	Blocs Tempo.
/var/lib/ongrid/qdrant/	root	Vector store.
/var/lib/ongrid/grafana/	472:472	État Grafana (dashboards, users, SA token).
/var/lib/ongrid/embeddings/	65532:65532	Cache de modèle BGE offline.
/var/log/ongrid/	mixed	Fichiers de log du manager.

Et après

• Check-list du premier démarrage — provider de modèle, rétention Prom, URL publique, fuseau horaire, le premier incident.
• Installation edge — enregistrer votre premier edge.
• Upgrade — le flux upgrade.sh, stage-then-swap, rollback .previous.
• Variables d'environnement — chaque variable d'env ONGRID_* que vous pouvez ajuster.