From f133cdd869e35a3bb0d7276f9c85ded062e05277 Mon Sep 17 00:00:00 2001 From: Elton Turing Date: Fri, 4 Sep 2026 18:56:24 +0200 Subject: [PATCH] Beschreibe den Betrieb von km auf hive.home MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- deploy/README.md | 81 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 57 insertions(+), 24 deletions(-) diff --git a/deploy/README.md b/deploy/README.md index 8cf14d2..97d63db 100644 --- a/deploy/README.md +++ b/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 -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). +## Läuft seit dem 2026-09-04: hive.home -**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 -habe sie beim Teamspace übersehen und eine eigene Unit gebaut, die dem Muster -zufällig fast glich. +| | | +|---|---| +| 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` | +| 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, - 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. +## Einrichten -Beim Teamspace hat sich gezeigt, wie gut das trägt, wenn die Referenz ihre -Gründe mitliefert: Dessen drei teuer gelernte Einstellungen liefen beim Nachbau -ohne eine einzige eigene Entdeckung durch — weil im Chart stand, *warum* sie so -sind, nicht nur *dass*. Diese Datei schuldet einem künftigen Chart dasselbe. +```bash +# 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 `_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.