homelab-infra/ops/grafana-influxdb/README.md

Grafana + InfluxDB 3 Core

Monitoring-Stack fuer Grafana + InfluxDB 3 Core. InfluxDB bleibt ohne Public Route; interne Writer wie Home Assistant koennen ueber einen gezielt gebundenen LAN-Port schreiben.

Quellen / Entscheidungen

• Grafana nutzt das offizielle OSS-Image grafana/grafana:12.4.3.
• InfluxDB nutzt influxdb:3.9.1-core, nicht latest, weil latest bei InfluxDB aktiv in Richtung InfluxDB 3 umgestellt wird.
• Grafana wird ueber Traefik + authelia@file,secure-headers@file unter grafana.kaleschke.info veroeffentlicht.
• InfluxDB bleibt ohne Traefik-Route. Der HTTP-Port 8181 kann fuer interne Writer wie Home Assistant ueber INFLUXDB_BIND_IP auf eine LAN-Adresse gebunden werden; Default ist 127.0.0.1.
• Grafana provisioning legt eine SQL-Datenquelle fuer InfluxDB 3 Core mit der Datenbank homelab an.
• Der Grafana-Datasource-Token liegt als Secret-Datei auf dem Host und wird beim Containerstart nur containerintern in die fuer Grafana-Provisioning noetige Environment-Variable geladen.
• Home Assistant schreibt mit der InfluxDB-v2-API-Kompatibilitaet nach InfluxDB 3; Details: docs/HOME_ASSISTANT_INFLUXDB_ECOWITT.md.

Initiale Einrichtung

1. Secret fuer Grafana anlegen:

   install -m 600 /dev/null /mnt/user/appdata/secrets/grafana_admin_password.txt
   

2. Offline-Admin-Token fuer InfluxDB 3 als JSON anlegen:

   {
     "token": "apiv3_REPLACE_WITH_STRONG_RANDOM_TOKEN",
     "name": "admin",
     "description": "Admin token for KalliLab InfluxDB 3 Core"
   }
   

   Pfad: /mnt/user/appdata/secrets/influxdb3_admin_token.json, Rechte 600.

3. Grafana-Datasource-Token anlegen. Fuer den ersten Start kann der Token aus influxdb3_admin_token.json verwendet werden; sobald ein eingeschraenkter Read-Token existiert, diesen hier eintragen:

   install -m 600 /dev/null /mnt/user/appdata/secrets/grafana_influxdb_token.txt
   

4. Provisioning-Datei aus dem Git-Checkout auf den Host-Appdata-Pfad kopieren:

   mkdir -p /mnt/user/appdata/grafana/provisioning/datasources
   cp /mnt/user/appdata/komodo/core/repos/homelab-infra/ops/grafana-influxdb/provisioning/datasources/influxdb.yml /mnt/user/appdata/grafana/provisioning/datasources/influxdb.yml
   chmod 644 /mnt/user/appdata/grafana/provisioning/datasources/influxdb.yml
   

5. Nach dem ersten Start die Datenbank anlegen:

   docker exec influxdb3-core influxdb3 create database homelab --token "$INFLUXDB3_AUTH_TOKEN"
   

Smoke-Test nach Deploy

• https://grafana.kaleschke.info oeffnet nach Authelia die Grafana-Loginseite.
• Grafana Connections -> Data sources -> InfluxDB 3 Core -> Save & test ist erfolgreich.
• InfluxDB bleibt ohne Public Route. Falls INFLUXDB_BIND_IP auf die LAN-IP gesetzt ist, ist Port 8181 nur im internen Netz fuer Writer wie Home Assistant erreichbar.

Rollback

• Stack in Komodo stoppen oder Git auf den letzten Stand ohne ops/grafana-influxdb zuruecknehmen.
• Persistente Daten liegen unter /mnt/user/appdata/grafana und /mnt/user/appdata/influxdb3; nicht automatisch loeschen.