hugin/BETRIEB.md

Hugin betreiben

Für den Betrieb: Container-Image, Datenbank, Sicherung. Deployment und Ingress liegen im Template des Betriebs. Hintergrund in KONZEPT.md Abschnitt 18.

Konfiguration

Nur über Umgebungsvariablen:

Umgebungsvariable	Bedeutung
HUGIN_DATABASE_URL	SQLite oder PostgreSQL
HUGIN_ADMIN_TOKEN	Plattform-Admin
HUGIN_BASE_URL	steht im Kopf verwalteter Dateien
HUGIN_DOWNLOAD_DIR	gebaute CLI-Programme für die Seite „Programm hugin“
HUGIN_CLI_MIN_VERSION	ältere CLIs meldet hugin check
HUGIN_RATE_LIMIT	Anfragen je Key und Minute (Standard 600)
HUGIN_FAILED_ATTEMPTS	falsche Keys je IP in 5 Minuten, danach 429 (Standard 20)
HUGIN_PROXY_IPS	Router, deren X-Forwarded-For gilt (Standard 127.0.0.1)
HUGIN_MAX_UPLOAD_MB	größter Request-Body (Standard 40)

Hinter dem OpenShift-Router HUGIN_PROXY_IPS auf das Netz des Routers setzen (z. B. 10.128.0.0/14). Sonst sehen Sperre und Audit nur die Adresse des Routers, und wenige falsche Keys sperren alle Nutzer für fünf Minuten.

Container-Image

Im Hugin-Repo liegt server/Dockerfile: Red Hat UBI 9 minimal mit Python 3.12, die Abhängigkeiten fest aus uv.lock. Das Image läuft als beliebiger Benutzer der Gruppe 0, wie OpenShift es vorgibt, und auch mit schreibgeschütztem Dateisystem.

docker build -t hugin server/
docker build --build-arg UBI=<spiegel>/ubi9/ubi-minimal:9.7 -t hugin server/   # eigener Spiegel

Was	Wie
Server starten	ohne Argument (Standard run), Port 8080
Migrationen	dasselbe Image mit Argument migrate, als Job vor jedem Rollout
Liveness-Probe	GET /healthz
Readiness-Probe	GET /readyz: Datenbank erreichbar und Migrationen aktuell; ohne migrate wird der Pod nicht bereit
Konfiguration	Umgebungsvariablen (oben); HUGIN_ADMIN_TOKEN als Secret
Logs	stdout

Datenbank: SQLite oder PostgreSQL

Beides funktioniert gleich; der Wechsel ist nur HUGIN_DATABASE_URL.

	SQLite	PostgreSQL
HUGIN_DATABASE_URL	nicht setzen: das Image nutzt /data/hugin.db	postgresql+psycopg://user:pw@host:5432/hugin
Volume	PVC auf /data, auch im Migrations-Job	keins
Pods	genau einer, Strategie Recreate	beliebig viele
Beim Ausrollen	kurz nicht erreichbar	ohne Unterbrechung
Sicherung	selbst: z. B. CronJob mit sqlite3 /data/hugin.db ".backup /sicherung/hugin.db"; die Datei nicht einfach kopieren, solange Hugin schreibt	übernimmt der Datenbankbetrieb
Gut für	Pilot, wenige Teams	breiter Einsatz, Hochverfügbarkeit

Fällt Hugin aus, laufen alle Agenten weiter, denn die Dateien liegen in den Repos; nur hugin sync geht dann nicht. Kurze Unterbrechungen beim Ausrollen sind deshalb unkritisch.

Von SQLite nach PostgreSQL umziehen: Dafür gibt es noch kein Werkzeug. Der Export enthält nur freigegebene Pakete, keine Keys, Personen oder Audit-Einträge.

Mehrere Pods: Das Rate-Limit zählt je Pod; mit drei Pods gelten also bis zu dreimal so viele Anfragen und Fehlversuche.

Export und CLI-Downloads

• Export: hugin-server export <ordner> --commit schreibt alle freigegebenen Pakete im Quellformat in einen Git-Ordner, z. B. als täglicher CronJob. Ergibt eine lesbare Historie und eine Notfall-Verteilung. Dasselbe als ZIP auf der Systemseite. --commit braucht git, das im Image fehlt; für den Betrieb ist es nicht nötig, die Datenbank-Sicherung enthält alles.
• CLI-Downloads: scripts/build-cli.sh <version> <ordner> baut das Programm hugin für macOS, Linux und Windows mit SHA256SUMS. Den Ordner einhängen und HUGIN_DOWNLOAD_DIR darauf setzen; ohne ihn zeigt die Seite „Programm hugin“ „Noch keine Programme hinterlegt“.

Clients mit lokalen MCP-Servern

Pakete mit lokalem MCP-Server (Python) installiert hugin sync auf jedem Rechner. Der Server braucht dafür nichts Zusätzliches (Upload bis HUGIN_MAX_UPLOAD_MB, Pakete bis 32 MB). Auf den Rechnern (Windows, Linux) muss bereitstehen:

Was	Wozu
hugin im PATH	Werkzeuge starten den Server über hugin mcp run; ein Alias reicht nicht
Python 3 (Windows: mit dem Starter py)	venv je Server; abweichend mit HUGIN_PYTHON
pip.conf (Linux ~/.config/pip/pip.conf oder /etc/pip.conf, Windows %APPDATA%\pip\pip.ini) mit dem Artifactory als index-url	pip lädt die Abhängigkeiten daraus, ohne Anmeldung
Schreibrecht auf ~/.local/share/mcp (Windows %USERPROFILE%\.local\share\mcp)	Ablage; abweichend mit HUGIN_MCP_HOME

Speicherplatz: je Server und Version eine venv (mit dem MCP-SDK etwa 50 MB). Alte Versionen löscht hugin mcp prune.