# 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

```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 `*/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.