Telematik

Dieses Projekt ist ein modulares System-Check- und Reporting-Toolkit in Python. Ziel ist es, Systeminformationen zu sammeln, Gesundheitschecks auszuführen und die Ergebnisse in einem einheitlichen Format bereitzustellen.

Install

git clone https://hex.wurzelraum.org/shukutils/shukelematik.git ~/.shukelematik
cd ~/.shukelematik
/bin/bash install.sh

1. Zieht den neuesten Code (falls Netzwerk verfügbar)
2. Installiert Systemabhängigkeiten via sudo apt-get install (python3-venv, inxi -- die einzige Stelle, an der sudo gebraucht wird; alles andere läuft im Userspace)
3. venv erstellen und Pakete installieren
4. Konfiguriert config.yml für die Maschine interaktiv (fragt nach Healthcheck-URL falls nötig)
5. Richtet Cronjob ein (im User-Crontab, nicht system-weit)

Updates: Einfach ./install.sh erneut ausführen.

Kein sudo apt-get: ./install.sh --skip-system-packages (beim Erstinstall) oder skip_system_packages: true in config.yml (bei einem Re-Run, da config.yml beim allerersten Lauf noch nicht existiert). python3-venv/inxi müssen dann selbst verfügbar sein.

Kein venv / rein im Userspace: ./install.sh --user-install (beim Erstinstall) oder use_user_install: true in config.yml (bei einem Re-Run) installiert stattdessen via pip install --user nach ~/.local -- braucht python3-venv gar nicht erst. Kombiniert mit --skip-system-packages landet nichts außerhalb des eigenen Home-Verzeichnisses; lediglich inxi fehlt dann (harmlos -- jeder Check läuft unabhängig, ein fehlendes inxi lässt nur InxiCheck mit einem Fehler im Report stehen, alles andere -- Docker, YunoHost, etc. -- läuft normal weiter). Falls pip sich wegen "externally-managed-environment" (PEP 668, Debian 12+/Ubuntu 23.04+) weigert, installiert install.sh automatisch mit --break-system-packages nach -- das umgeht nur pips eigene Absicherung, landet aber weiterhin nur in ~/.local, nicht system-weit.

Funktionsrahmen

• Systemmetriken überprüfen: Festplattennutzung, Paketversionen, Netzwerke, Docker, Boot-Status, etc.
• Läuft als Cronjob
• Sendet Bericht als .json an healthchecks.io Instanz
• Funktioniert hinter Firewalls (nur ausgehende HTTPS-Verbindung nötig)
• GPG für secrets in öffentlichen Repos unterstützt

Paketstruktur

shukelematik/
├── install.sh              # Haupt-Installations-/Update-Script
├── telematik/
│   ├── checks/             # Gesundheitscheck-Module
│   │   ├── base.py         # BaseCheck-Klasse
│   │   ├── diskusage.py    # Festplattennutzungs-Check
│   │   ├── docker.py       # Docker-Container-Check
│   │   └── ...
│   ├── util
│   │   └── config.py       # Config-Load/Save-Utilities
│   ├── configure.py        # Initiales Setup-Script
│   └── ping.py             # Ping Skript
│   └── report.py           # Berichterstellung
├── config.yml              # Maschinenspezifische Config (gitignored)
├── example-config.yml      # Template-Config
└── requirements.txt

Secrets (optional)

Erstelle secrets.yml mit deinen Zugangsdaten:

HC_API_URL: "https://hc-ping.com/api-url"
HC_API_TOKEN: "geheimes-token"

Verschlüsseln für Commit ins Repo:

gpg --symmetric --cipher-algo AES256 secrets.yml
# secrets.yml.gpg committen, secrets.yml ist in .gitignore

Einen Check hinzufügen

Erstelle telematik/checks/deincheck.py:

from telematik.checks.base import BaseCheck

class DeinCheck(BaseCheck):
    def probe(self):
        # Daten sammeln
        return {"key": "value"}
    
    @staticmethod
    def is_healthy(data, config=None):
        # Gesundheit bewerten
        return True
    
    @staticmethod
    def summary(data):
        # Ausgabe formatieren
        return "Status: OK"

Registriere in telematik/ping.py:

from telematik.checks.deincheck import DeinCheck

checks = [
    # ... bestehende Checks
    DeinCheck(config),
]

Idee

1. Cron führt ping.py aus
2. Jeder Check's probe() sammelt Systemdaten
3. is_healthy() bewertet, ob das System gesund ist
4. JSON-Payload wird an /success oder /fail Endpunkt gesendet
5. Zentrales Dashboard fragt healthchecks.io-API für aggregierte Ansicht ab