# 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` |
| 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 `_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.