Server-Installation (docker compose)

Die kanonische Installation ist ein eigenständiges Tarball und ein sudo ./install.sh. Das Tarball liefert jedes Docker-Image (ongrid, ongrid-web, singchia/frontier) aus, sodass kein Docker-Hub-Pull nötig ist — die Installation funktioniert in restriktiven Netzwerken und air-gapped.

Für Air-Gapped-Spezifika siehe Air-Gapped-Installation. Für eine schnellere Anleitung siehe Schnellstart. Für die systemd-native Installation (kein Docker) siehe Linux-Server-Plattform.

Voraussetzungen

Ein Linux-Host mit:

• 4 GB RAM Minimum, 8 GB empfohlen (Prometheus + Loki + Tempo + MySQL + Manager leben alle hier).
• 20 GB freier Speicherplatz unter /var/lib/ongrid (das Datenroot). Passen Sie mit ONGRID_DATA_DIR=… an, wenn Sie es woanders haben wollen — NFS / iSCSI / NVMe funktionieren alle; es ist ein einfaches Bind-Mount.
• Docker ≥ 24 mit dem docker compose v2 Subcommand (docker compose version sollte ausdrucken).
• openssl — wird von install.sh verwendet, um das selbstsignierte TLS-Zertifikat beim ersten Boot zu erstellen, wenn tls.crt / tls.key nicht bereits vorhanden sind.
• Eingehendes TCP/443 offen von Ihrem Browser + jeder Edge.
• Eingehendes TCP/40012 offen von jeder Edge (der Frontier-Broker).
• Eine öffentliche IP oder Domain, die alle Edges erreichen können. Das geht in ONGRID_PUBLIC_URL und ist die einzig häufigste Fehlkonfiguration.

Verwenden Sie keine private IP für ONGRID_PUBLIC_URL

Der Installer erkennt eine IP automatisch und fordert Sie auf zu bestätigen. Wenn Sie eine 10.x / 192.168.x / 172.16-31.x-Adresse akzeptieren, aber Ihre Edges im öffentlichen Internet leben, werden Logs und Traces stillschweigend nicht gepusht. Der Steuerungsebenen-Tunnel funktioniert weiterhin (er geht unabhängig durch nginx), sodass die Edge in der UI gesund aussieht — aber Loki und Tempo bleiben leer.

Installation

# 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

Nützliche Flags:

Flag	Was
--mode systemd	Wechseln zur nativen systemd-Installation (kein Docker). Dispatcht zu systemd/install-systemd.sh. Siehe Linux-Server-Plattform.
--with-deps	Nur systemd. Automatische Installation von mariadb + nginx + grafana via apt/dnf, gepinnte prom- / loki- / tempo- / qdrant-Binaries mit sha256-Verify ziehen.
--profile monitoring	Nur Compose. Prometheus auf Port 9090 zum Host exponieren (nützlich für Laptop-Dev; standardmäßig aus in Prod).
--no-seed	Nur Compose. Banner-Ausgabe des Admin-Bootstrap überspringen (beim erneuten Ausführen einer Installation).
--force	Nur Compose. Über einer bestehenden Installation neu installieren (bewahrt .env und Datenvolumen).

Was install.sh tut

Der Reihe nach:

1. Preflight. Verifiziert, dass die docker-CLI in $PATH ist, der Daemon erreichbar ist und docker compose v2 vorhanden ist. Bricht früh ab bei einem davon.

2. Konfigurationen lagern nach ${ONGRID_INSTALL_DIR:-/opt/ongrid}/:

   • docker-compose.yml, .env.example, VERSION, frontier.yaml,
   • prometheus.yml (in den prom-Container unter /etc/prometheus/ bind-gemountet),
   • prometheus-rules.yml (ADR-026 Self-Observability-Alarme),
   • loki-config.yaml, tempo-config.yaml,
   • grafana/-Provisionierung,
   • searxng/-Einstellungen,
   • edge/ (per-arch Edge-Binaries + Plugin-Binaries + Upgrade-Bundle).

3. Host-Datenverzeichnisse erstellen unter ${ONGRID_DATA_DIR:-/var/lib/ongrid}/ und chown sie auf die uid, mit der jedes Container-Image läuft:

   • mysql/ → 999:999 (mysql:8.0)
   • prometheus/ → 65534:65534 (prom läuft als nobody)
   • loki/ → 10001:10001
   • tempo/ → 10001:10001
   • grafana/ → 472:472
   • embeddings/ → 65532:65532 (Manager nonroot User)

   Dies beim ersten Boot zu verpassen, ist, was prom/loki/tempo/grafana mit permission denied on /<datadir> crashen lässt.

4. Das gebündelte Embedding-Modell für Offline-RAG lagern — /var/lib/ongrid/embeddings/fast-bge-small-zh-v1.5/. Wenn Sie bereits ein benutzerdefiniertes Modell ausgetauscht haben, lässt der Installer es in Ruhe.

5. nginx-Konfiguration refreshen aus dem Tarball und, wenn keine Zertifikate in ${INSTALL_DIR}/certs/ vorhanden sind, ein selbstsigniertes Zertifikat generieren, gültig 365 Tage (CN=ongrid, SAN: DNS:ongrid, DNS:localhost, IP:127.0.0.1).

6. Docker-Images laden aus images/ongrid.tar, images/frontier.tar, images/ongrid-web.tar via docker load. Kein Registry-Pull erforderlich.

7. .env erstellen oder wiederverwenden. Wenn ${INSTALL_DIR}/.env existiert, behalten Sie es (--force überschreibt operator-editiertes .env NICHT). Wenn nicht, von .env.example kopieren. Dann Lücken mit starken zufälligen Werten füllen:

   • MYSQL_ROOT_PASSWORD, MYSQL_PASSWORD — 24 Zeichen,
   • ONGRID_JWT_SECRET — 64 Zeichen,
   • ONGRID_ADMIN_PASSWORD — 20 Zeichen (für das finale Banner aufgezeichnet),
   • GRAFANA_ADMIN_PASSWORD — 20 Zeichen.

8. Nach ONGRID_PUBLIC_URL fragen, wenn leer. 30-Sekunden-Countdown, Default = bestmögliche Vermutung. Liest /dev/tty, sodass es curl ... | bash überlebt.

9. docker compose up -d mit --env-file .env. Kein -f-Argument, sodass docker-compose.override.yml automatisch lädt, wenn Sie eines für Tweaks hinzugefügt haben.

10. Pollt https://localhost/healthz bis zu 60 Sekunden via nginx. Das /healthz des Managers gibt 200 zurück, sobald MySQL erreichbar und der Agent-Kernel verdrahtet ist.

11. Druckt das Installations-Banner — Web-URL, API-URL, Tunnel-Endpunkt, Bootstrap-Admin-E-Mail + Passwort (nur bei der Erstinstallation).

Nach der Installation

Sie sehen ein Banner wie:

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

Notieren Sie das Admin-Passwort

Das Bootstrap-Passwort wird einmal angezeigt. Es wird auch in /opt/ongrid/.env (Mode 0600) gespeichert. Wenn Sie beide verlieren, zurücksetzen via die reset-admin-password-CLI oder durch direktes Editieren der DB — siehe Erstinbetriebnahme-Checkliste.

Den Stack verifizieren

# 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

Das TLS-Zertifikat ersetzen

Das selbstsignierte Zertifikat ist für Trials in Ordnung, aber jeder Browser warnt. Für Produktion legen Sie ein echtes Zertifikat (Let's Encrypt, Ihre Corp-CA, was auch immer) in /opt/ongrid/certs/ ab:

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 und upgrade.sh überschreiben nie operator-bereitgestellte Zertifikate.

Wildcards funktionieren

nginx bedient *.crt / *.key aus certs/; die einzigen Dateinamen, nach denen der Container sucht, sind tls.crt und tls.key. Symlinks sind in Ordnung, wenn Ihr Cert-Manager (certbot, acme.sh, cert-manager) die kanonische Kopie woanders behält.

Wo Dinge landen

Pfad	Eigentümer	Zweck
/opt/ongrid/docker-compose.yml	root	Compose-Definition.
/opt/ongrid/.env	root, 0600	Secrets + Tunables.
/opt/ongrid/certs/	root, 0700	tls.crt, tls.key.
/opt/ongrid/edge/	root	Edge-Binaries, Upgrade-Bundle (edge-bundle-<arch>-<ver>.tar.gz), install.sh, apply-pending-upgrade.sh. Read-only über nginx unter /edge/ bedient.
/opt/ongrid/prometheus.yml	root	Prom Scrape + remote_write Config.
/opt/ongrid/grafana/	root	Provisionierungs-Yamls (Datenquellen, Dashboards).
/var/lib/ongrid/mysql/	999:999	MySQL-Daten. Sichern Sie das.
/var/lib/ongrid/prometheus/	65534:65534	Prom TSDB. 90d Retention, 20GB Cap standardmäßig.
/var/lib/ongrid/loki/	10001:10001	Loki Chunks + Index.
/var/lib/ongrid/tempo/	10001:10001	Tempo-Blöcke.
/var/lib/ongrid/qdrant/	root	Vector-Store.
/var/lib/ongrid/grafana/	472:472	Grafana-Zustand (Dashboards, Users, SA-Token).
/var/lib/ongrid/embeddings/	65532:65532	Offline-BGE-Modell-Cache.
/var/log/ongrid/	gemischt	Manager-Log-Dateien.

Was als Nächstes

• Erstinbetriebnahme-Checkliste — Model-Provider, Prom-Retention, öffentliche URL, Zeitzone, der erste Incident.
• Edge-Installation — Ihre erste Edge registrieren.
• Upgrade — der upgrade.sh-Fluss, Stage-then-Swap, .previous-Rollback.
• Umgebungsvariablen — jede ONGRID_*-Umgebungsvariable, die Sie tunen können.