Erstinbetriebnahme-Checkliste

Direkt nachdem install.sh fertig ist und Sie sich als Bootstrap-Admin angemeldet haben, gehen Sie diese Liste durch. Nichts davon ist erforderlich, um „Dinge zu sehen" — der Schnellstart funktioniert ohne irgendetwas davon — aber jeder Punkt schließt eine Lücke, bevor Sie das System an ein Team übergeben.

1. ONGRID_PUBLIC_URL korrekt setzen

Wahrscheinlich der wichtigste Punkt. Diese URL ist, was Ihre Edges für die Datenebene verwenden — Logs pushen an <url>/loki/api/v1/push, Traces pushen an <url>/v1/traces.

Prüfen, was install.sh eingefüllt hat:

sudo grep '^ONGRID_PUBLIC_URL=' /opt/ongrid/.env

Wenn Sie eine interne Adresse akzeptiert haben, aber Ihre Edges im öffentlichen Internet leben, werden Logs und Traces stillschweigend fehlschlagen — der Tunnel funktioniert weiterhin (er hat seinen eigenen Port), sodass die Edge gesund aussieht.

Zum Beheben:

# Edit
sudo sed -i 's|^ONGRID_PUBLIC_URL=.*|ONGRID_PUBLIC_URL=https://ops.example.com|' /opt/ongrid/.env

# Restart the affected services
sudo docker compose -f /opt/ongrid/docker-compose.yml --env-file /opt/ongrid/.env up -d ongrid nginx

Sie müssen Edges nicht neu deployen; der Agent liest den Datenebenen-Endpunkt periodisch vom Manager neu.

Siehe ONGRID_PUBLIC_URL.

2. Einen Standard-LLM-Provider konfigurieren

Out of the Box ist kein Provider konfiguriert. Der Agent weigert sich zu denken.

1. Settings → Models. Wählen Sie eines aus:
   • OpenAI (gpt-5.4 Default)
   • Anthropic (claude-opus-4-7 Default)
   • Zhipu (glm-4.7 Default)
   • DeepSeek (deepseek-v4-flash Default)
   • Gemini (gemini-2.5-pro Default)
   • Kimi (kimi-k2.6 Default)
   • Custom OpenAI-kompatibel (vLLM, Ollama, OpenRouter, Corporate-Relay…)
2. Den API-Key einfügen. Optional: Standardmodell in „Advanced" überschreiben.
3. Save. Pre-Registration ist hot — kein Restart.
4. Auf derselben Seite Default provider auf das gerade verdrahtete setzen.

Mischen Sie nicht default_provider und Per-Route-Modelle

Der „Default" treibt Back-End-LLM-Aufrufe (Alarm-Untersuchung, Übersetzen, Zusammenfassen). Der Modell-Picker im Chat-Header ist ein Per-Thread-Override — nützlich für „versuche Opus bei dieser einen Frage", aber der Site-Default ist, was für Cron-Jobs und Incidents läuft.

Siehe die Einträge Routing & Default und Budget & Limits unter Modelle in der Seitenleiste.

3. Einen Benachrichtigungskanal konfigurieren

Auch wenn Sie noch keine Alarmregeln haben, verdrahten Sie einen Kanal, sodass zukünftige Incidents irgendwo landen können.

Das empfohlene Starter-Paar:

• Webhook-Kanal an einen generischen Incoming-Webhook-Collector (Sie können ihn später immer entfernen) — beweist, dass der Benachrichtigungspfad funktioniert.
• Ein IM-Kanal — Telegram ist am einfachsten, weil Sie nur ein Bot-Token und eine Chat-ID brauchen; Slack/Lark/DingTalk/WeCom brauchen mehr Setup.

Siehe Kanäle-Übersicht.

4. Die Manager-Zeitzone setzen

Zeitstempel in Incident-Timelines und Alarm-Events folgen der Zeitzone des Managers. Default ist UTC innerhalb des Containers; für eine UI, die zu Ihrem Team passt:

# Set TZ in compose env. Edit /opt/ongrid/docker-compose.yml or drop a
# /opt/ongrid/docker-compose.override.yml with:
services:
  ongrid:
    environment:
      TZ: Asia/Shanghai

sudo docker compose -f /opt/ongrid/docker-compose.yml --env-file /opt/ongrid/.env up -d ongrid

Für das AI-Output-Locale (antwortet das LLM in Englisch oder Chinesisch) setzen Sie ONGRID_DEFAULT_LOCALE. Default en; gültige Werte passen zu Ihren UI-Übersetzungen (en, zh-CN, ja, …). Kanäle können pro Kanal überschreiben; manuelle UI-Anfragen folgen Accept-Language.

5. Prometheus-Retention entscheiden

Die Compose setzt standardmäßig 90 Tage / 20 GB Cap. Zum Ändern:

# /opt/ongrid/docker-compose.override.yml
services:
  prometheus:
    command:
      - --storage.tsdb.path=/prometheus
      - --storage.tsdb.retention.time=30d
      - --storage.tsdb.retention.size=10GB
      - --web.enable-remote-write-receiver
      - --web.enable-lifecycle
      - --web.external-url=/prometheus/
      - --web.route-prefix=/prometheus/
      - --config.file=/etc/prometheus/prometheus.yml

sudo docker compose -f /opt/ongrid/docker-compose.yml --env-file /opt/ongrid/.env up -d prometheus

Für Loki-Retention editieren Sie /opt/ongrid/loki-config.yaml und starten Sie den loki-Container neu. Für Tempo editieren Sie /opt/ongrid/tempo-config.yaml.

6. Entscheiden, ob Sie die eingebauten Loki / Tempo behalten

Wenn Sie bereits Managed-Log/Trace-Backends betreiben (Grafana Cloud, Honeycomb, Splunk, Ihre eigenen VictoriaLogs / VictoriaTraces…), können Sie:

• Die eingebetteten behalten als das Data-Sink, durch das der Agent abfragt (günstigster Pfad, keine zusätzliche Infra).
• Sie austauschen, indem Sie den Agenten auf die Managed-URL via ONGRID_LOG_QUERY_URL / ONGRID_TRACE_QUERY_URL ausrichten und jeder Edge promtail / otelcol neu konfigurieren, um dorthin direkt zu pushen.

Für ein Hybrid-Setup (Edges pushen an beide) legen Sie ein benutzerdefiniertes promtail.yaml / otelcol.yaml in /etc/ongrid-edge/ auf jeder Edge ab, und der Agent nimmt es auf.

Siehe Logs-Fähigkeit und Traces-Fähigkeit.

7. Das selbstsignierte TLS-Zertifikat ersetzen

Für Trial-Use ist es in Ordnung. Für Prod ist das Zertifikat in /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 und upgrade.sh überschreiben nie Operator-Zertifikate.

8. /var/lib/ongrid und /opt/ongrid/.env sichern

Alles Zustandsbehaftete lebt unter diesen zwei Pfaden:

• /opt/ongrid/.env — Secrets (JWT, MySQL, Admin-Passwort, Embed-Keys).
• /var/lib/ongrid/mysql/ — der gesamte operative Zustand. Alles, was Sie nicht verlieren können, lebt hier: Edges, Alarmregeln, Incidents, Kanal-Konfigurationen, Audit-Log, benutzerdefinierte Skills, Wissens-Metadaten.
• /var/lib/ongrid/qdrant/ — Vektor-Embeddings (rekonstruierbar aus Quelldokumenten, aber teuer).
• /var/lib/ongrid/prometheus/, loki/, tempo/ — Telemetrie; nur sichern, wenn Sie lange Retention brauchen.

Ein einfaches cron + rsync (oder restic) dieser beiden Roots gibt Ihnen Disaster Recovery. Restore = Stack stoppen, Verzeichnisse ersetzen, Stack starten.

9. Einen echten Admin-Account einrichten

Die E-Mail des Bootstrap-Admins ist, was Sie (oder install.sh) in ONGRID_ADMIN_EMAIL gesetzt haben. Für ein echtes Team:

1. Settings → Identity → Users → Invite user für jeden echten Operator.
2. Jedem eine Rolle zuweisen: admin, user oder viewer (ADR-022 RBAC).
   • admin — volle Kontrolle.
   • user — kann mit dem Agenten chatten, Incidents ansehen, Alarme stummschalten. Toolbag auf ClassSafe gefiltert.
   • viewer — Read-only Chat (keine Write-Skills), Read-only Incidents.
3. Den Bootstrap-Admin degradieren, wenn Sie wollen, oder einfach aufhören, ihn zu verwenden.

10. Den ersten Incident triggern (Smoke-Test)

Eine der eingebauten Regeln zum Feuern zwingen. Am einfachsten: eine Ihrer Edges stoppen.

sudo systemctl stop ongrid-edge

Innerhalb ONGRID_ALERT_EDGE_OFFLINE_THRESHOLD (Default 90s) plus dem Evaluator-Intervall (Default 5m) feuert die edge_offline-Regel. Die UI:

• Alerts — neues Event.
• Incidents — neue Incident-Gruppierung, die das Event gruppiert.
• Channels — Ihr verdrahteter Kanal empfängt eine Karte.

Wenn Sie einen IM-Kanal eingerichtet haben, antworten Sie dem Bot mit „investigate this". Der Incident Investigator läuft end-to-end und postet einen Bericht zurück.

Edge neu starten:

sudo systemctl start ongrid-edge

Incident bewegt sich automatisch zu mitigated, wenn die Regel aufhört zu feuern; Sie markieren ihn aus der UI als resolved.

Was als Nächstes

• Kanäle-Übersicht — verdrahten Sie Ihre echten On-Call-Kanäle.
• Alarme-Fähigkeit — verfassen Sie benutzerdefinierte Regeln über die 6 eingebauten hinaus.
• Upgrade — wenn v0.7.X+1 ausgeliefert wird.
• Referenz / env — jeder ONGRID_*-Tunable.