# Hugin betreiben

Für den Betrieb: Container-Image, Datenbank, Sicherung. Deployment und Ingress liegen im
Template des Betriebs. Hintergrund in [KONZEPT.md](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.

```sh
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`.