km/deploy/README.md

deploy — die lauffähige Referenz

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).

Läuft seit dem 2026-09-04: hive.home

Wirt	LXC 171144 (hive.home) auf neo, neben caddy und radicale
Dienst	/srv/km/compose.yml, oci enable km / oci restart km
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
Doku	https://hive.home/doku/info/ — statische MkDocs-Seite aus dem info-Checkout, von km nach jedem Pull mit Änderung gebaut (/srv/km/data/site/info, Caddy file_server)
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

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).

Einrichten

# im LXC
mkdir -p /srv/km/data
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 */doku/ stehen in der .gitignore der Ablage.

Doku lesen: MkDocs statt SilverBullet

Andreas, 04.09.: SilverBullet ist für die Doku nicht das Richtige — sie soll aussehen wie sie soll, lesen statt editieren, ohne Auto-Commit-Problem. km baut deshalb jede Quelle mit mkdocs.yml nach jedem Pull mit Änderung als statische Seite (mkdocs-material im Image, ~60 s auf dem LXC) nach /srv/km/data/site/<name>; Caddy mountet das Verzeichnis read-only und liefert es unter /doku/<name>/ aus. Ein Baufehler lässt die alte Seite stehen und erscheint im Lauf-Ergebnis (site_<name>: FEHLER …).

Oberfläche: Seitenleiste

SilverBullet hat keine Ordnernavigation. Die liefert das TreeView-Plug (_plug/treeview.plug.js in der Ablage, committet), konfiguriert in der Seite CONFIG (Position links, Library/CONFIG/index ausgeblendet, Knopf „Seitenleiste ein/aus" oben rechts). „Plugs: Update" aus der Oberfläche hat das Plug am 04.09. nicht geladen; die Datei wurde von Hand aus raw.githubusercontent.com/joekrill/silverbullet-treeview/main/treeview.plug.js abgelegt. Die Startseite index.md ist eine km-Seite mit Links, nicht mehr SilverBullets Begrüßung.

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.