Linux (Server)

Der Manager wird als Docker-Image (ongrid:<version>) ausgeliefert und wird über docker compose bedient. Beide kommen aus dem Release-Tarball, das durch make package produziert wird — kein apt install ongrid, kein hostseitiger Daemon.

Unterstützte Distributionen

Wir betreiben den Manager Tag für Tag auf den folgenden Hosts. Alles, was Docker Engine 24+ läuft, sollte funktionieren; die untenstehende Liste ist das, was explizites Testen pro Release bekommt.

Distribution	Getestet auf
Ubuntu	22.04 LTS, 24.04 LTS
Debian	12 (bookworm)
RHEL	9
Rocky Linux	9
AlmaLinux	9

CentOS 7 wird nicht unterstützt — seine glibc und systemd sind zu alt für den gebündelten Compose-Stack und haben Upstream-EOL erreicht.

Erforderliche Software

• Docker Engine 24.0 oder später. Ältere Releases vermissen --platform-Verklemmungen, auf die sich make docker-build stützt, und brechen extra_hosts: host-gateway.
• Docker Compose v2 (das docker compose-CLI-Plugin, nicht das Legacy-docker-compose-Binary). Die Compose-Datei unter deploy/docker-compose.yml lässt absichtlich den Top-Level-version:-Key weg, was v1 ablehnt.
• systemd für den Host. Der Manager selbst registriert keine systemd-Unit — das Install-Skript deploy/install/server-install.sh stützt sich nur auf systemd, um Docker zu starten — aber Auto-Restart bei Reboot braucht aktiviertes docker.service.
• iptables / nftables ist in Ordnung; beide Backends funktionieren.

Keine erforderlichen Kernel-Module über das hinaus, was Docker selbst braucht (overlayfs, Namespaces, cgroups v1 oder v2).

Ressourcen-Untergrenzen

Ressource	Untergrenze	Komfortabel	Warum
CPU	2 vCPU	4 vCPU	Der Manager-Go-Prozess, Prometheus, Loki, Tempo, Grafana, MySQL leben alle auf demselben Host.
Speicher	4 GB	8 GB	Prometheus + Loki zusammen können im Leerlauf 1,5 GB treffen. Headroom hält den OOM-Killer von MySQL fern.
Disk	20 GB	100 GB	Prometheus-Retention ist 90 Tage / 20 GB standardmäßig (siehe --storage.tsdb.retention.* in der Compose-Datei). Loki + Tempo teilen den Rest.
Netzwerk	10 Mbps	100 Mbps	Telemetrie ist die Datenebene — Log-Shipping von vielen Edges kann eine dünne Pipe lange vor dem Manager selbst sättigen.

Die 20-GB-Untergrenze nimmt an, dass Sie nur mit einer Handvoll Edges testen. Sobald Sie ~25 Hosts überschreiten, die Metriken + Logs + Traces liefern, planen Sie 200 GB nur ein, um 30 Tage Loki zu behalten.

Ports

Port	Richtung	Protokoll	Was es ist
443	eingehend	HTTPS	nginx — SPA, REST API, Log-/Trace-Ingest
80	eingehend	HTTP	nginx-Redirect auf 443
40012	eingehend	TCP (geminio)	Frontier-Broker — jede Edge wählt das
3306	lokal exponiert	TCP	MySQL — in Produktion an 127.0.0.1 binden
9090	lokal exponiert	HTTP	Prometheus — in Produktion an 127.0.0.1 binden
9100	eingehend (optional)	HTTP	Manager /metrics — für externen Prometheus zum Scrapen

Nur 443, 80 und 40012 müssen vom öffentlichen Internet (oder dem Netzwerk Ihrer Edge-Flotte) erreichbar sein. Alles andere bleibt in Produktion an localhost gebunden — nginx fronted die API, und Grafana / Prometheus / Loki / Tempo werden über das Docker-Netzwerk erreicht.

Was der Compose-Stack läuft

Aus deploy/docker-compose.yml:

Service	Image	Rolle
mysql	mysql:8.0	Primärer Store des Managers (Benutzer, Edges, Devices, Alarmregeln, Sessions).
ongrid	ongrid:<version>	Manager — Go-Binary aus cmd/ongrid gebaut.
nginx	ongrid-web:<version>	TLS-Terminierung, SPA, /api/* Reverse-Proxy, /edge/* statisch für das Install-Bundle.
frontier	singchia/frontier:1.2.5	Geminio-Broker; Edge-Tunnel-Endpunkt (ADR-007).
prometheus	prom/prometheus:v2.54.0	Metrik-Store + remote_write-Receiver (ADR-009).
loki	grafana/loki:3.4.0	Log-Store (ADR-012).
tempo	grafana/tempo:2.5.0	Trace-Store (ADR-013).
searxng	searxng/searxng:latest	Selbstgehostetes Such-Backend für das web_search-Skill.
grafana	grafana/grafana-oss:11.1.4	Dashboard-Embed für die Monitor-Seite.

Die Compose-Datei ist die Produktions-Form — es gibt keine zweite „Prod"-Datei. Knöpfe überschreiben über den env-Block (ONGRID_* — siehe Umgebungsvariablen) statt das YAML zu forken.

TLS

nginx terminiert TLS unter Verwendung von Zertifikaten, die aus deploy/certs/ (cert.pem, key.pem) bind-gemountet werden. Für den ersten Boot generiert das Install-Skript ein selbstsigniertes Zertifikat; ersetzen Sie es jederzeit durch ein echtes und docker compose restart nginx. Let's Encrypt wird via ein Sidecar-Muster unterstützt, dokumentiert in deploy/README.md.

SELinux + AppArmor

Beide funktionieren out of the Box. Die Compose-Datei mountet keine sensiblen Host-Pfade read-write; die Bind-Mounts (./edge, ./nginx, ./certs, ./grafana/provisioning) sind alle :ro. Wenn Ihre SELinux-Policy strikte Labels auf Bind-Mounts erzwingt, hängen Sie :Z an die Mount-Strings innerhalb docker-compose.override.yml an.

Upgraden

make package           # produces dist/out/ongrid-vX.Y.Z-linux-amd64.tar.xz
scp dist/out/ongrid-vX.Y.Z-linux-amd64.tar.xz host:/tmp/
ssh host /tmp/upgrade.sh

upgrade.sh lebt neben dem Tarball und macht den idempotenten Tanz: das neue Image laden, eine temporäre docker-compose.override.yml schreiben, die den neuen Tag pinnt, docker compose up -d, das vorherige Image nach einer gesunden Minute prunen. Siehe Upgrade.

Was NICHT funktioniert

• Podman + podman-compose: die Compose-Datei verwendet Docker-spezifische Kurzschreibweise (extra_hosts: host-gateway, :Z-SELinux-Semantik), die podman entweder inkompatibel parst oder ignoriert. Wir testen es nicht.
• K3s-Host-Modus-Networking: funktioniert für den Manager, aber der Edge-Installer ist um bare systemd gebaut — siehe Kubernetes für das DaemonSet-Muster.
• OpenRC / runit / s6: der Manager-Container kümmert sich nicht, aber der Docker-Daemon des Hosts muss beim Boot hochkommen. Wenn Ihr Init-System das kann, sind Sie in Ordnung.