Beschreibe den Betrieb von km auf hive.home

Wirt, Ports, Volume, Routen über Caddy, Einrichtung und die drei Dinge,
die beim ersten Aufsetzen Zeit gekostet haben.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

deploy/README.md

@@ -1,31 +1,64 @@
 # deploy — die lauffähige Referenz
 
-`km.lan` als LXC mit podman-compose, wie jeder andere Dienst im Haus.
+`km` als compose-Dienst über **`oci`** (`42i-oci`), wie jeder andere Dienst im
+Haus. Das ist **nicht** der Notbehelf, bis es ein Chart gibt: Wer den Dienst
+auf k8s bringen will, sieht hier, welche Images, welche Umgebung und welche
+Volumes er braucht — und kann sein Chart gegen etwas Laufendes prüfen. Das
+Chart selbst gehört zu hive (Schnitt im Haupt-README).
 
-Das ist **nicht** der Notbehelf, bis es ein Chart gibt. Es ist die Vorführung
+## Läuft seit dem 2026-09-04: hive.home
-des Dienstes: Wer ihn auf k8s bringen will, sieht hier, welche Images, welche
-Umgebung und welche Volumes er braucht — und kann sein Chart gegen etwas
-Laufendes prüfen statt gegen eine Beschreibung. Das Chart selbst gehört zu hive
-(siehe den Schnitt im Haupt-README).
 
-**Noch leer.** Wenn es soweit ist, gehört hierher eine `compose.yml` nach dem
+| | |
-Muster von `info/deployment/team/` — und der Betrieb läuft über **`oci`**
+|---|---|
-(`42i-oci`), nicht über eine eigene systemd-Unit. Das ist die Hausvorgabe; ich
+| Wirt | LXC **171144** (`hive.home`) auf `neo`, neben `caddy` und `radicale` |
-habe sie beim Teamspace übersehen und eine eigene Unit gebaut, die dem Muster
+| Dienst | `/srv/km/compose.yml`, `oci enable km` / `oci restart km` |
-zufällig fast glich.
+| Container | `km` (API + Takt, Port 8390) und `km-ui` (SilverBullet, Port 3000), beide `network_mode: host` |
+| Volume | `/srv/km/data/ablage` — Git-Checkout von `git.home/ahmann/km` (privat); daneben `km-index.sqlite` und `km-ingest-state.json` |
+| Quelle | `git.home`, Organisation `ahmann`, Namespace `familie`, Klassifikation `home` |
+| Oberfläche | `https://hive.home/km/` (SilverBullet, Login aus OpenBao `elton/km-home`) |
+| API | `https://hive.home/km/api/v1/…`, `https://hive.home/km/health` |
+| Takt | alle 5 Minuten: ziehen, Gitea einlesen, indexieren, Geändertes committen und pushen |
+| Vektoren | **aus** (`KM_EMBED=0`) — erst, wenn es einen Abnehmer gibt; die Ollama-Instanz auf s18 ist vom LXC aus ohne VLAN5-Route nicht erreichbar |
+| 42i-hc | `/srv/km/health` prüft die API und den letzten Lauf |
 
-Was dort außerdem gelernt wurde und hier gelten wird:
+Caddy (`/srv/caddy/Caddyfile`) routet unter `hive.home`: `/km/api/*` und
+`/km/health` an km (Präfix `/km` abgestreift), `/km*` an SilverBullet
+(`SB_URL_PREFIX=/km`), alles andere an Radicale. Der Pfadraum an der Wurzel
+bleibt geteilt (hive/core#61).
 
-- **Rechte am Volume.** Läuft der Prozess im Image unter einer eigenen UID,
+## Einrichten
-  muss das Datenverzeichnis ihr gehören. Im Chart erledigt das `fsGroup`; bei
-  podman gibt es niemanden, der es von selbst tut, und der Fehler zeigt sich
-  erst bei der ersten Schreiboperation — wortlos.
-- **Konfiguration in die Datenbank oder ins Volume, nicht in eine Datei im
-  Container.** Sonst ist jede Einstellung nach dem nächsten Neustart weg, und
-  es sieht aus, als wäre sie nie gemacht worden.
-- **Secrets aus OpenBao**, nie in der compose-Datei und nie in argv.
 
-Beim Teamspace hat sich gezeigt, wie gut das trägt, wenn die Referenz ihre
+```bash
-Gründe mitliefert: Dessen drei teuer gelernte Einstellungen liefen beim Nachbau
+# im LXC
-ohne eine einzige eigene Entdeckung durch — weil im Chart stand, *warum* sie so
+mkdir -p /srv/km/data
-sind, nicht nur *dass*. Diese Datei schuldet einem künftigen Chart dasselbe.
+cp compose.yml /srv/km/          # build-Kontext dort: ./build/image
+cp health /srv/km/ && chmod +x /srv/km/health
+cp env.example /srv/km/.env && chmod 600 /srv/km/.env   # dann ausfüllen
+oci enable km && oci start km
+```
+
+Das Image heißt `git.42i.org/spine/km:latest`. Solange es keine Registry
+mit anonymem Lesezugriff gibt (git.42i.org verlangt Login, und ein
+Firmen-Token gehört nicht auf den Familien-LXC), wird es **im LXC gebaut**:
+`image/` hinkopieren nach `/srv/km/build/image` und
+`podman build --network=host -t git.42i.org/spine/km:latest .` — ohne
+`--network=host` scheitert der Bau im unprivilegierten LXC an `/dev/net/tun`.
+
+## Drei Dinge, die beim ersten Aufsetzen Zeit gekostet haben
+
+1. **podman-compose kennt keine Defaults.** `${VAR:-x}` wird wörtlich
+   durchgereicht; km bekam den Platzhalter als Repo-Namen. Deshalb steht
+   **jede** Variable in der `.env` (`env.example`), und die Konfiguration
+   verwirft Werte, die mit `${` beginnen.
+2. **Die interne CA.** `git.home` hat ein Zertifikat von `acme.lan`. `requests`
+   benutzt sein eigenes CA-Bündel und kennt sie nicht — deshalb wird das
+   Bündel des Wirts eingehängt und `REQUESTS_CA_BUNDLE` darauf gesetzt, wie
+   bei `caddy`.
+3. **SilverBullet ist zuerst da.** Beide Container mounten dasselbe Volume;
+   die Oberfläche legt ihre Dateien an, bevor km klonen kann. km
+   initialisiert die Ablage deshalb **in place** und holt den Remote-Stand
+   dazu; `.silverbullet*` und `_plug/` stehen in der `.gitignore` der Ablage.
+
+Und aus dem Teamspace übernommen: Konfiguration ins Volume, nicht in eine
+Datei im Container; Secrets aus OpenBao, nie in der compose-Datei und nie in
+argv.