Run the containers with the systemd configuration, 1:1

The containers now read the unchanged .env of the matching systemd instance
(/home/llmadmin/mindnet_dev/.env, /home/llmadmin/mindnet/.env) and use the
same Qdrant, Ollama, vault and collection prefix, so both can be compared
side by side. Only container-specific values are overridden: host service
addresses (host.docker.internal instead of 127.0.0.1) and the read-only vault.

- deploy/appenv.py derives the vault mount and prefix from that .env and
  rejects application keys in the container-only file.
- Remove the separate dev Qdrant, the synthetic test vault and the import step.
- UI binds 0.0.0.0 like systemd; API stays loopback by default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
LarsandClaude Opus 5.5 committed 2026-10-28 17:22:08 +01:00
1 parent eae30775e3
commit 6cdad8b046
20 files changed
+373 -415

No files matched your search

+40 -43
View File
@@ -3,7 +3,7 @@ doc_type: operations_manual
audience: devops, deployment_engineer
scope: docker, compose, container_security, nas_mount
status: draft
version: 0.2.0
version: 0.3.0
context: "Container-Betrieb von Mindnet (Dev/Prod) auf llm-node. Vorbereitung, noch keine produktive Umschaltung."
---
@@ -11,20 +11,29 @@ context: "Container-Betrieb von Mindnet (Dev/Prod) auf llm-node. Vorbereitung, n
Stand: 28.10.2026. **Status: Dev aktiv (Push auf `develop`), Prod vorbereitet, nicht aktiv.** Produktion läuft unverändert über systemd und `.gitea/workflows/deploy.yml` (siehe [Deployment Guide](04_deployment_guide.md)). Der Containerstand basiert auf dem stabilen `main`-Verhalten **ohne** Privacy Gateway.
**Grundsatz: 1:1-Migration.** Der Container betreibt dieselbe Anwendung mit derselben Konfiguration wie die jeweilige systemd-Instanz, damit beide parallel verglichen werden können. Er liest deren `.env` unverändert. Konfigurationsänderungen sind nachgelagerte Schritte.
## 1. Überblick
| | Dev | Prod |
| --- | --- | --- |
| Compose-Datei | `deploy/compose.dev.yml` | `deploy/compose.prod.yml` |
| Projektname | `mindnet-dev` | `mindnet-prod` |
| API (nur `127.0.0.1`) | 8012 | 8011 |
| UI (Bind-Adresse konfigurierbar) | 8512 | 8511 |
| Qdrant | eigener Container `qdrant`, Volume `mindnet-dev_qdrant` | bestehende Host-Instanz, unverändert |
| Collection-Präfix | `mindnet_dev` (fest) | `mindnet` (env-Datei, von Preflight geprüft) |
| Vault | Testdaten, nur lesend | NAS-Vault, nur lesend |
| Ollama | gemeinsamer Host-Dienst | gemeinsamer Host-Dienst |
| Vergleichsinstanz (systemd) | 8002/8502, `/home/llmadmin/mindnet_dev` | 8001/8501, `/home/llmadmin/mindnet` |
| Anwendungskonfiguration | `/home/llmadmin/mindnet_dev/.env`, unverändert | `/home/llmadmin/mindnet/.env`, unverändert |
| Container-Angaben | `/home/llmadmin/docker/mindnet-dev/container.env` | `/home/llmadmin/docker/mindnet/container.env` |
| Compose-Datei / Projekt | `deploy/compose.dev.yml` / `mindnet-dev` | `deploy/compose.prod.yml` / `mindnet-prod` |
| API (Standard nur `127.0.0.1`) | 8012 | 8011 |
| UI (Standard `0.0.0.0`, wie systemd) | 8512 | 8511 |
| Qdrant, Ollama | gemeinsame Host-Dienste, wie systemd | gemeinsame Host-Dienste, wie systemd |
| Präfix, Vault | aus der `.env` der systemd-Instanz | aus der `.env` der systemd-Instanz |
Die Ports kollidieren weder untereinander noch mit systemd (8001/8002/8501/8502). Dev und Prod können später parallel zu den systemd-Diensten laufen, was einen Vergleich vor der Umschaltung erlaubt.
Die Ports kollidieren weder untereinander noch mit systemd (8001/8002/8501/8502), damit Container und systemd parallel laufen und verglichen werden können.
**Abweichungen vom heutigen Verhalten, bewusst und nur diese:**
- **Adressen der Host-Dienste:** `QDRANT_URL` und `MINDNET_OLLAMA_URL` zeigen auf `host.docker.internal`. `127.0.0.1` wäre im Container der Container selbst. Ziel sind dieselben Dienste.
- **Vault nur lesend:** Zwei Instanzen sollen nicht parallel in denselben Vault schreiben. Außerdem ist R2 offen. Speichern aus der Container-UI schlägt deshalb fehl, lesen und suchen funktionieren.
- **Cloud-Keys:** Enthält die `.env` Cloud-Keys, startet der Container nur, wenn in der Container-Datei `MINDNET_ALLOW_CLOUD_EGRESS=true` steht. Mit `true` verhält er sich wie heute; die Entscheidung trifft der Betreiber.
- **Bind-Adresse der API:** Standard ist `127.0.0.1`; über `MINDNET_API_BIND` lässt sie sich wie bei systemd auf `0.0.0.0` setzen.
Alle Dateien liegen unter `deploy/`. Dieser Ordner gehört nicht zu `DEPLOY_DIRS` des bestehenden Workflows und wird daher nicht automatisch auf den Server synchronisiert. Der alte Ordner `docker/` (MiniLM-Embed-Dienst, Port 8990) bleibt unverändert, siehe Abschnitt 9.
@@ -69,7 +78,7 @@ Der aktuelle Lock wurde mit `--exclude-newer 2026-01-22` erzeugt, also dem Stand
| Vault fehlt, Sentinel nicht lesbar, Mount nicht `ro` (`statvfs` `ST_RDONLY`) | Arbeiten auf leerem NAS-Mountpunkt; Schreiben in den Vault (R2) |
| `MINDNET_OLLAMA_URL`/`QDRANT_URL` fehlen oder zeigen auf `localhost`/`127.0.0.1` | App fiele still auf `127.0.0.1` zurück, im Container also auf sich selbst |
Die Werte für Umgebung, Dimension und Vault stehen in den Compose-Dateien unter `environment` und lassen sich nicht über die env-Datei überschreiben.
Umgebung, Dimension, Schreibschutz und die Adressen der Host-Dienste stehen in den Compose-Dateien unter `environment` und haben Vorrang vor beiden env-Dateien. Präfix und Vault-Pfad kommen aus der `.env` der systemd-Instanz. Die Präfix-Regel gilt trotzdem: Dev nur `*_dev`, Prod nie.
`preflight --live` prüft zusätzlich **nur lesend** aus dem Container heraus, also über dasselbe Netz wie die API:
@@ -84,13 +93,14 @@ Die Werte für Umgebung, Dimension und Vault stehen in den Compose-Dateien unter
Netzwerkfehler enden als klarer Abbruch mit Exit-Code 1, nicht als Traceback.
```bash
docker compose -f deploy/compose.dev.yml --env-file deploy/env/dev.env run --rm --no-deps api preflight --live
docker compose -f deploy/compose.dev.yml --env-file "$MINDNET_ENV_FILE" run --rm --no-deps api preflight --live # Variablen wie in Abschnitt 7
```
## 4. Vault auf dem NAS
- **Gleicher Vault wie systemd:** `deploy/appenv.py` liest `MINDNET_VAULT_ROOT` aus der `.env`. Ein relativer Pfad wird wie bei systemd gegen das `WorkingDirectory` (Ordner der `.env`) aufgelöst und im Container unter `/app/<pfad>` eingehängt, ein absoluter Pfad 1:1. Dadurch zeigt derselbe Wert im Container auf dasselbe Verzeichnis. Fehlt der Wert, gilt der App-Default `./vault_master`.
- Der Bind-Mount ist `read_only: true`, mit `create_host_path: false` (kein stilles Anlegen) und `propagation: rslave`. Ein später wieder eingehängtes NAS wird dadurch im Container sichtbar, sofern der Host-Mountpunkt `shared` ist.
- **Sentinel:** Standard ist `_system/dictionary/edge_vocabulary.md` relativ zum Vault, einstellbar über `MINDNET_VAULT_SENTINEL`. Die Datei existiert im echten Vault bereits; am NAS muss also nichts angelegt werden. Ein Testdaten-Vault für Dev braucht sie ebenfalls.
- **Sentinel:** Standard ist `_system/dictionary/edge_vocabulary.md` relativ zum Vault, einstellbar über `MINDNET_VAULT_SENTINEL`. Liegt sie im Vault der systemd-Instanz woanders, wird `MINDNET_VAULT_SENTINEL` in der Container-Datei gesetzt.
- **NAS beim Start nicht verfügbar:** Die API startet nicht. `restart: unless-stopped` versucht es mit Backoff weiter. Die UI hängt an der gesunden API.
- **NAS fällt im Betrieb aus:** Der Healthcheck meldet die API als `unhealthy`. Lesende Abfragen gegen Qdrant laufen weiter. Speichern ist wegen des schreibgeschützten Mounts ohnehin ausgeschlossen. `/ingest/save` würde ohne `ro` den fehlenden Vault-Ordner per `os.makedirs` neu anlegen; genau das verhindert der Mount.
- **Berechtigungen:** Der Container läuft als UID 10001. Der Vault muss für diese UID **lesbar** sein, z. B. über `others: r-x` oder eine passende Gruppe auf dem NAS-Export. Bei CIFS-Mounts gelten `uid`/`gid`/`file_mode` aus den Mount-Optionen des Hosts. Prüfen, ohne am NAS etwas zu ändern:
@@ -111,7 +121,9 @@ docker inspect qdrant --format '{{json .HostConfig.PortBindings}}'
Sind Qdrant oder Ollama nur an `127.0.0.1` gebunden, ist der Host-Gateway nicht erreichbar. Lösungsmöglichkeiten, jede nur mit Freigabe: Ollama an die Bridge-Adresse binden (`OLLAMA_HOST`), den Prod-Container an das bestehende Docker-Netz von `qdrant` anhängen (externes Netz), oder `network_mode: host` für die API. Keine davon ist umgesetzt.
Die API hat keine Authentisierung und wird daher nur an `127.0.0.1` veröffentlicht. Die UI erreicht sie intern über `http://api:8000`. Für LAN-Zugriff auf die UI wird `MINDNET_UI_BIND` auf die LAN-IP des Hosts gesetzt.
Ollama ist seit dem 28.10.2026 für die Docker-Netze freigegeben: `OLLAMA_HOST=0.0.0.0:11434` und `ufw allow from 172.16.0.0/12 to any port 11434`, das LAN bleibt gesperrt. Die Prod-Qdrant ist über ihren veröffentlichten Port 6333 erreichbar.
Die API hat keine Authentisierung und wird standardmäßig nur an `127.0.0.1` veröffentlicht. Die UI erreicht sie intern über `http://api:8000`. Die UI ist wie bei systemd im LAN erreichbar (`MINDNET_UI_BIND=0.0.0.0`).
## 6. Härtung
@@ -122,27 +134,20 @@ Für `api` und `ui`: `read_only`-Rootfs, `tmpfs /tmp`, `cap_drop: ALL`, `no-new-
Normalerweise über das Deploy-Skript (Abschnitt 8), auch manuell:
```bash
MINDNET_ENV_FILE=/home/llmadmin/docker/mindnet-dev/dev.env deploy/deploy.sh dev
export MINDNET_APP_ENV_FILE=/home/llmadmin/mindnet_dev/.env # systemd-Dev, unverändert
export MINDNET_ENV_FILE=/home/llmadmin/docker/mindnet-dev/container.env # aus deploy/env/dev.env.example
deploy/deploy.sh dev
```
Einzelschritte von Hand:
Für Einzelschritte von Hand braucht Compose zusätzlich die abgeleiteten Vault-Werte:
```bash
cp deploy/env/dev.env.example deploy/env/dev.env # ausfüllen; *.env ist git-ignoriert
docker compose -f deploy/compose.dev.yml --env-file deploy/env/dev.env build
docker compose -f deploy/compose.dev.yml --env-file deploy/env/dev.env run --rm --no-deps api preflight
docker compose -f deploy/compose.dev.yml --env-file deploy/env/dev.env up -d --wait
eval "$(python3 deploy/appenv.py "$MINDNET_APP_ENV_FILE" "$MINDNET_ENV_FILE")"
export MINDNET_VAULT_HOST_PATH MINDNET_VAULT_TARGET MINDNET_IMAGE_TAG=dev-manual
docker compose -f deploy/compose.dev.yml --env-file "$MINDNET_ENV_FILE" up -d --wait
```
**Dev-Daten aufbauen** (nur Dev-Qdrant, Präfix fest `mindnet_dev`): Der Vault-Mount ist nur lesend; der Import liest die Dateien und schreibt ausschließlich in Qdrant.
```bash
DEV="docker compose -f deploy/compose.dev.yml --env-file deploy/env/dev.env"
$DEV run --rm --no-deps api preflight && \
$DEV run --rm --entrypoint python api -m scripts.import_markdown --vault /vault --prefix mindnet_dev --apply
```
Hinweis: Ein Befehl hinter `run` ersetzt nur `CMD`; `entrypoint.py` lehnt unbekannte Modi ab. Für Skripte wird der Entrypoint deshalb mit `--entrypoint python` ersetzt. Der Preflight muss dann vorher separat laufen, wie oben gezeigt. Die übrigen Prüfungen bleiben wirksam: fester Präfix `mindnet_dev`, Dev-Qdrant und schreibgeschützter Vault.
Einen Import startet der Container-Workflow nicht; die Daten sind dieselben wie bei systemd.
**Ohne Cloud-Keys** (Prod-Standard) ruft der stabile Code für Cloud-Profile Ollama mit der Cloud-Modell-ID auf. Das scheitert zunächst und endet über `fallback_profile` bei `identity_safe` (phi3:mini). Chat funktioniert damit lokal, aber mit Verzögerung durch Fehlversuche (Review R4).
@@ -155,15 +160,7 @@ Gleiches Muster wie Kansho, aber auf dem eigenen Runner des Zielhosts (heute llm
| `.gitea/workflows/deploy-dev.yml` | Push `develop`, manuell | **aktiv** (G3) |
| `deploy/gitea-workflows/deploy-prod.yml` | Push `main`, manuell | Vorlage. Aktivierung bei G5, im **selben Commit** `git rm .gitea/workflows/deploy.yml` (systemd), sonst deployen beide |
**Dev-Testdaten:** Der Dev-Workflow spiegelt vor jedem Deploy den synthetischen Test-Vault `deploy/testvault/` nach `/home/llmadmin/docker/mindnet-dev/testvault` (erzeugt mit `scripts/make_test_vault.py`, dazu synthetisches `edge_vocabulary.md`/`graph_schema.md`). Fehlt `dev.env`, legt er sie beim ersten Lauf aus `deploy/env/dev.env.example` an, ohne Cloud-Keys und mit dem Test-Vault als `MINDNET_VAULT_HOST_PATH`. Eine vorhandene `dev.env` wird nie überschrieben. Die Ordner `vault/` und `vault_master/` im Repo enthalten persönlich wirkende Inhalte und werden **nicht** verwendet.
Test-Vault in die Dev-Qdrant importieren (manuell, nach dem ersten grünen Deploy; Embeddings über Ollama):
```bash
cd <checkout> && export MINDNET_ENV_FILE=/home/llmadmin/docker/mindnet-dev/dev.env
docker compose -f deploy/compose.dev.yml --env-file "$MINDNET_ENV_FILE" run --rm --entrypoint python api \
-m scripts.import_markdown --vault /vault --prefix mindnet_dev --apply
```
Fehlt die Container-Datei, legt der Workflow sie beim ersten Lauf aus `deploy/env/<env>.env.example` an. Sie enthält nur Ports, Bind-Adressen und Freigaben. Eine vorhandene Datei wird nie überschrieben. `deploy/appenv.py` bricht ab, wenn darin Anwendungswerte stehen, damit sie die `.env` der systemd-Instanz nicht überschreiben kann.
Prod nur über einen Merge-Commit `develop` → `main` (`git merge --no-ff develop`), wie bei Kansho.
@@ -172,15 +169,15 @@ Beide Workflows rufen nur `deploy/deploy.sh dev|prod` auf. Jeder Schritt bricht
1. Container-Tests im Test-Image mit `--network none` (Preflight, Erreichbarkeit gegen Fake-Server, statische Compose-/Workflow-Prüfungen), **blockierend**.
2. Volle Testsuite mit `--network none`, **informativ**, bis die 17 bekannten Fehler behoben sind ([Migrationsplan §4](../05_Development/05_docker_migration_plan.md)). Ohne Netzwerk kann kein Test einen echten Dienst erreichen.
3. Image bauen, Tag `<env>-<commit>`.
4. `preflight --live` in einem Wegwerf-Container (Prod mit `--no-deps`; Dev startet dafür die eigene Qdrant).
4. Vault und Präfix aus der systemd-`.env` ableiten (`deploy/appenv.py`), danach `preflight --live` in einem Wegwerf-Container.
5. `up -d --wait` (Healthchecks) und danach `deploy/smoke.py` über die veröffentlichten Ports, also aus Sicht des Hosts:
- API `/healthz`: Status `ok`, erwartetes Präfix.
- API `/admin/stats`: Vektorgröße 768; die API erreicht Qdrant (Collection-Counts ≠ −1).
- UI `/_stcore/health`.
- Prod zusätzlich `--require-data`: alle Collections lesbar, Notes nicht leer.
6. Erfolg: Der Tag wird in `last_good_tag` neben der env-Datei vermerkt. Prod bei Fehler: Rückkehr zum letzten erfolgreichen Tag und erneuter Smoke-Test; der Workflow bleibt trotzdem rot.
- `--require-data`: alle Collections lesbar, Notes nicht leer, denn die Daten der systemd-Instanz sind vorhanden.
6. Erfolg: Der Tag wird in `last_good_tag` neben der Container-Datei vermerkt. Verwaiste Container früherer Stände entfernt `--remove-orphans`. Prod bei Fehler: Rückkehr zum letzten erfolgreichen Tag und erneuter Smoke-Test; der Workflow bleibt trotzdem rot.
Die env-Dateien liegen nur auf dem Host (`/home/llmadmin/docker/mindnet-dev/dev.env`, `/home/llmadmin/docker/mindnet/prod.env`). Die Compose-Dateien lesen sie über `MINDNET_ENV_FILE`; Secrets landen nicht im Runner-Workspace.
Beide env-Dateien liegen nur auf dem Host (Tabelle in Abschnitt 1). Compose liest sie direkt über `MINDNET_APP_ENV_FILE` und `MINDNET_ENV_FILE`; Secrets landen nicht im Runner-Workspace.
**Unterschiede zu Kansho, bewusst:**
@@ -192,7 +189,7 @@ Die env-Dateien liegen nur auf dem Host (`/home/llmadmin/docker/mindnet-dev/dev.
| Image | `build --no-cache`, kein Tag | Hash-Lock, Tag pro Commit, Rollback in Prod |
| Zustand des Hosts | `.env` im Checkout | env-Datei und `last_good_tag` außerhalb des Checkouts |
**Umzug auf einen anderen Mini-PC:** Runner dort registrieren, in beiden Workflows `runs-on` und `MINDNET_ENV_FILE` anpassen, env-Dateien und Vault-Mount einrichten. Hostspezifisch ist sonst nur `host.docker.internal` (über `host-gateway`, funktioniert auf jedem Linux-Docker).
**Umzug auf einen anderen Mini-PC:** Runner dort registrieren, in beiden Workflows `runs-on`, `MINDNET_APP_ENV_FILE` und `MINDNET_ENV_FILE` anpassen. Hostspezifisch ist sonst nur `host.docker.internal` (über `host-gateway`, funktioniert auf jedem Linux-Docker).
## 9. Altbestand `docker/` (MiniLM)