From 3bbe0ffb178c98d6ea8149edac1eb600a823c074 Mon Sep 17 00:00:00 2001
From: Elton Turing <elton@42i.org>
Date: Tue, 8 Sep 2026 11:30:23 +0200
Subject: [PATCH] Doku: Umstiegsrezept aufs Hausmuster ./data:/data umgestellt

---
 docs/betrieb.md | 48 ++++++++++++++++++++++++++++++++++--------------
 1 file changed, 34 insertions(+), 14 deletions(-)

diff --git a/docs/betrieb.md b/docs/betrieb.md
index c26f9b7..8cc22b0 100644
--- a/docs/betrieb.md
+++ b/docs/betrieb.md
@@ -181,14 +181,29 @@ noch nicht.
 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:
+Layout wandert vorab ins Hausmuster: alles Laufzeitige unter `./data`
+(siehe [data/README.md](../data/README.md)), der Compose-Dienst mountet
+`./data:/data`. Einmalig migrieren — **Kopie, nicht Verschieben**, damit die
+Binary-Unit bis zum Umschalten lauffähig bleibt:
+
+```sh
+cd /srv/llmrouter
+mkdir data
+cp config.json key-acls.json keys.json model-blocklist.json data/
+cp -a log data/log        # state.json + aa-cache.json wandern mit
+```
+
+`cp -a log` ist der entscheidende Schritt: `state.json` (Zuordnung) und
+`aa-cache.json` (AA-Index-Cache) liegen im logDir. Mit ihnen startet der
+Container sofort mit frischer Zuordnung; ohne sie gibt es eine Startlücke
+(~40 s bei `LLMROUTER_LASTTEST=0`, sonst ≈210k Token), in der Stufen mit 503
+antworten („noch nicht aufgelöst").
 
 ```yaml
 services:
   llmrouter:
     image: git.42i.org/spine/llmrouter:latest
-    env_file: /srv/llmrouter/.env
+    env_file: [.env]
     environment:
       # .env trägt die Host-Pfade — im Container auf /data übersteuern:
       LLMROUTER_CONFIG: /data/config.json
@@ -196,28 +211,33 @@ services:
       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"]
+    volumes: ["./data:/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").
+- `logDir` steht in `config.json` auf `./log` — relativ zur Config
+  aufgelöst, im Container also `/data/log`, ohne Config-Änderung.
 - 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.
+  LXC; nach dem Umstieg mit den data/-Pfaden aufrufen
+  (`KEYS_FILE=/srv/llmrouter/data/keys.json` …). Die alten flachen Dateien
+  (`config.json`, `keys.json`, die `.bak`-Kopien) können erst aufgeräumt
+  werden, wenn der Umstieg hält.
+- Ablauf: compose-Datei + Unit (Muster caddy.service) anlegen →
+  `podman-compose up -d` → `/health` prüfen (Zeitstempel aktuell) →
+  `systemctl stop/disable llmrouter`. Rollback: Binary-Unit wieder
+  aktivieren, Container stoppen.
 - Updates danach: `podman pull` + Container neu starten; CI published
-  `:latest` (und `:sha-<sha>`) bei jedem Push auf main.
+  `:latest` (und `:sha-<sha>`) bei jedem Push auf main (paths-Filter —
+  Doku-Commits bauen nicht).
 
 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.
+funktioniert. Der Mount ist hostseitig — `./data:/data` ergibt dem Container
+gegenüber denselben `/data`-Inhalt wie der getestete Mount. Container und
+Image danach rückstandsfrei entfernt.
 
 ## Störung