From fb3e37b208ebab8a0d96e54ae9e2bed71a0679a7 Mon Sep 17 00:00:00 2001
From: Elton Turing <elton@42i.org>
Date: Tue, 8 Sep 2026 11:12:07 +0200
Subject: [PATCH] Doku: Umstieg aufs Image geprueft, Rezept und Fallstricke
 ergaenzt

---
 docs/betrieb.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 53 insertions(+), 2 deletions(-)

diff --git a/docs/betrieb.md b/docs/betrieb.md
index 678b369..c26f9b7 100644
--- a/docs/betrieb.md
+++ b/docs/betrieb.md
@@ -158,8 +158,9 @@ lief. Weitere Log-Wege (SQLite, Stats-Binary): [referenz.md](referenz.md).
 ## Wartung und Deploy
 
 Quelle dieses Projekts ist dieses Repo (`spine/llmrouter`). Der Prod-Einsatz
-läuft weiter als statisches Binary im LXC (Stand 2026-09-08); ein Umstieg auf
-das Docker-Image ist offen und nicht dringend.
+läuft weiter als statisches Binary im LXC (Stand 2026-09-08); der Umstieg aufs
+Image ist **geprüft und machbar**, das Rezept steht unten — vollzogen ist er
+noch nicht.
 
 1. Änderung in diesem Repo (Config, Code), committen, pushen. CI baut und
    published danach `git.42i.org/spine/llmrouter:latest` — für den
@@ -175,6 +176,49 @@ das Docker-Image ist offen und nicht dringend.
    tauscht den Inode und `caddy reload` sieht die alte Datei. Nach Änderung
    `oci restart caddy`. Quelle: [caddy/Caddyfile](caddy/Caddyfile).
 
+### Umstieg aufs Image (geprüft am 2026-09-08, ausstehend)
+
+Voraussetzungen alle erfüllt: podman 5.4.2 im LXC (kein Docker nötig —
+Muster wie `caddy.service`: podman-compose + systemd-oneshot), das Image ist
+öffentlich pullbar (anonym, wie `42i/caddy`), Multi-Arch enthält amd64.
+Produktions-Layout ist **flach** (`/srv/llmrouter/*`, kein `data/`-Unterverzeichnis)
+— der ganze Ordner wird als `/data` gemountet:
+
+```yaml
+services:
+  llmrouter:
+    image: git.42i.org/spine/llmrouter:latest
+    env_file: /srv/llmrouter/.env
+    environment:
+      # .env trägt die Host-Pfade — im Container auf /data übersteuern:
+      LLMROUTER_CONFIG: /data/config.json
+      LLMROUTER_ACLS: /data/key-acls.json
+      KEYS_FILE: /data/keys.json
+      MODEL_BLOCKLIST: /data/model-blocklist.json
+    ports: ["127.0.0.1:4010:4010"]   # Caddy zeigt weiter auf localhost:4010
+    volumes: ["/srv/llmrouter:/data"]
+    restart: unless-stopped
+```
+
+- **`log/` im selben Mount lassen.** `state.json` (Zuordnung) lebt im
+  logDir; ein isoliertes Log-Verzeichnis startet ohne Zuordnung — bis das
+  Auffrischen durch ist (~40 s bei `LLMROUTER_LASTTEST=0`, sonst ≈210k Token)
+  antworten Stufen mit 503 („noch nicht aufgelöst").
+- Sidecar-Binaries (`llmrouter-resolve`, `-stats`, `-keys`) bleiben auf dem
+  LXC; das Image enthält nur den Server.
+- Ablauf: compose-Datei + Unit anlegen → `podman-compose up -d` → `/health`
+  prüfen (Zeitstempel aktuell, nicht 1970) → `systemctl stop/disable
+  llmrouter`. Rollback: Unit wieder aktivieren, Container stoppen.
+- Updates danach: `podman pull` + Container neu starten; CI published
+  `:latest` (und `:sha-<sha>`) bei jedem Push auf main.
+
+Prüfstand 2026-09-08 (Probelauf auf dem LXC, Produktion unberührt, Port 4011,
+Log-Dir nach /tmp ausgelagert): Image startet mit der Produktions-Config (25
+Aliasse, 21 Rollen, 12 Token), `/models` **byte-identisch** zur Binary, Chat
+via `/chat/completions` 200 über beide Wege (`42i/marvin-2609:medium` →
+`z-ai/glm-5.3-flash`), komplette Zuordnungs-Auffrischung im Container
+funktioniert. Container und Image danach rückstandsfrei entfernt.
+
 ## Störung
 
 | Symptom | Prüfen | Tun |
@@ -204,6 +248,13 @@ starten — LiteLLM bedient die `2608`-Namen weiter, die `2609`-, `alt/`- und
 
 ## Verlauf
 
+- 2026-09-08: **Umstieg aufs Image geprüft.** Probelauf des CI-Images auf
+  dem LXC neben dem Binary (Port 4011): Konfig-/ACL-/Keys-Parität
+  (`/models` byte-identisch), Chat 200 über beide Wege, Zuordnungs-Refresh
+  läuft im Container. Rezept und Fallstricke stehen jetzt in
+  [Wartung und Deploy](#wartung-und-deploy); Prod läuft weiter auf der
+  Binary. Dazu Registry-Login-Fix in der CI (vertauschte Secret-Werte,
+  401er am Vormittag) und Login-Kommentar korrigiert.
 - 2026-09-08: **Umzug nach `spine/llmrouter`** (git.42i.org). Das komplette
   Projekt verließ das Repo `42i/agents` (Historie per subtree split bewahrt);
   dazu Docker-Image, Compose-Demo mit `./data`-Mount und Gitea-Actions-CI