diff --git a/deploy/entrypoint.py b/deploy/entrypoint.py index 08922b4..1a1f0d8 100644 --- a/deploy/entrypoint.py +++ b/deploy/entrypoint.py @@ -102,19 +102,31 @@ def _is_read_only_mount(path: Path) -> bool: return bool(os.statvfs(path).f_flag & os.ST_RDONLY) +DEFAULT_VAULT_ROOT = "./vault_master" # Default aus app/config.py + + def check_vault() -> None: if not _flag("MINDNET_VAULT_REQUIRED", "true"): return - root = Path(os.getenv("MINDNET_VAULT_ROOT", "")) - if not str(root) or not root.is_dir(): + root = Path(os.getenv("MINDNET_VAULT_ROOT") or DEFAULT_VAULT_ROOT) + if not root.is_dir(): raise PreflightError(f"Vault-Verzeichnis fehlt: '{root}'.") - # Ein ausgefallenes NAS hinterlässt einen leeren Mountpunkt; der Sentinel unterscheidet das. - sentinel = root / os.getenv("MINDNET_VAULT_SENTINEL", "_system/dictionary/edge_vocabulary.md") + # Ein ausgefallenes NAS hinterlässt einen leeren Mountpunkt. try: - with sentinel.open("rb") as f: - f.read(1) + empty = next(root.iterdir(), None) is None except OSError: - raise PreflightError(f"Vault-Sentinel nicht lesbar: '{sentinel}' (NAS nicht gemountet?).") from None + raise PreflightError(f"Vault '{root}' nicht lesbar (NAS nicht gemountet?).") from None + if empty: + raise PreflightError(f"Vault '{root}' ist leer (NAS nicht gemountet?).") + # Optional: zusätzlich eine bestimmte Datei verlangen (z. B. auf dem NAS-Vault). + sentinel_name = os.getenv("MINDNET_VAULT_SENTINEL", "").strip() + if sentinel_name: + sentinel = root / sentinel_name + try: + with sentinel.open("rb") as f: + f.read(1) + except OSError: + raise PreflightError(f"Vault-Sentinel nicht lesbar: '{sentinel}' (NAS nicht gemountet?).") from None if _flag("MINDNET_VAULT_READONLY", "true") and not _is_read_only_mount(root): raise PreflightError(f"Vault '{root}' ist nicht schreibgeschützt gemountet (':ro' erforderlich).") diff --git a/deploy/healthcheck.py b/deploy/healthcheck.py index 9e514ed..cd4f965 100644 --- a/deploy/healthcheck.py +++ b/deploy/healthcheck.py @@ -28,10 +28,14 @@ def main(mode: str) -> int: print(f"health: {mode} nicht erreichbar ({type(e).__name__})") return 1 if mode == "api" and os.getenv("MINDNET_VAULT_REQUIRED", "true").lower() == "true": - root = Path(os.getenv("MINDNET_VAULT_ROOT", "")) - sentinel = root / os.getenv("MINDNET_VAULT_SENTINEL", "_system/dictionary/edge_vocabulary.md") - if not sentinel.is_file(): - print(f"health: Vault-Sentinel fehlt ({sentinel})") + root = Path(os.getenv("MINDNET_VAULT_ROOT") or "./vault_master") + sentinel_name = os.getenv("MINDNET_VAULT_SENTINEL", "").strip() + try: + ok = (root / sentinel_name).is_file() if sentinel_name else next(root.iterdir(), None) is not None + except OSError: + ok = False + if not ok: + print(f"health: Vault leer oder nicht lesbar ({root})") return 1 return 0 diff --git a/docs/04_Operations/04_docker_deployment.md b/docs/04_Operations/04_docker_deployment.md index 8826a6c..f2addea 100644 --- a/docs/04_Operations/04_docker_deployment.md +++ b/docs/04_Operations/04_docker_deployment.md @@ -75,7 +75,7 @@ Der aktuelle Lock wurde mit `--exclude-newer 2026-01-22` erzeugt, also dem Stand | `MINDNET_ENV` ∈ {dev, prod}; `COLLECTION_PREFIX` explizit; Dev nur `*_dev`, Prod nie `*_dev` | Dev schreibt in Prod-Collections; stiller Default `mindnet` | | `VECTOR_DIM == 768`, Profil `embedding_expert` = ollama/`nomic-embed-text`/768, kein abweichendes `MINDNET_EMBEDDING_MODEL` | stiller Rückfall auf 384 (MiniLM) in `qdrant.py` bzw. auf das Chat-Modell als Embedding | | Cloud-Key gesetzt ohne `MINDNET_ALLOW_CLOUD_EGRESS=true` | unmaskierte Vault-Inhalte an OpenRouter/Gemini | -| Vault fehlt, Sentinel nicht lesbar, Mount nicht `ro` (`statvfs` `ST_RDONLY`) | Arbeiten auf leerem NAS-Mountpunkt; Schreiben in den Vault (R2) | +| Vault fehlt, leer oder nicht lesbar, optionaler Sentinel fehlt, 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 | 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. @@ -100,7 +100,7 @@ docker compose -f deploy/compose.dev.yml --env-file "$MINDNET_ENV_FILE" run --rm - **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/` 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`. Liegt sie im Vault der systemd-Instanz woanders, wird `MINDNET_VAULT_SENTINEL` in der Container-Datei gesetzt. +- **Sentinel:** Standardmäßig wird nur geprüft, dass der Vault lesbar und nicht leer ist; einen bestimmten Aufbau verlangt der Container nicht (wie systemd). Optional kann `MINDNET_VAULT_SENTINEL` in der Container-Datei eine Datei relativ zum Vault vorschreiben, z. B. `_system/dictionary/edge_vocabulary.md` für den NAS-Vault. - **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: diff --git a/tests/test_container_preflight.py b/tests/test_container_preflight.py index a4c681b..b9f8cba 100644 --- a/tests/test_container_preflight.py +++ b/tests/test_container_preflight.py @@ -107,13 +107,11 @@ def test_no_cloud_keys_needs_no_ack(env): # --- Vault / NAS ----------------------------------------------------------------------- -def _vault(tmp_path, with_sentinel=True): +def _vault(tmp_path, with_content=True): root = tmp_path / "vault" root.mkdir() - if with_sentinel: - sentinel = root / "_system" / "dictionary" / "edge_vocabulary.md" - sentinel.parent.mkdir(parents=True) - sentinel.write_text("# vocab", encoding="utf-8") + if with_content: + (root / "notiz.md").write_text("# Notiz", encoding="utf-8") return root @@ -125,7 +123,21 @@ def test_vault_missing_directory(env, tmp_path): def test_vault_empty_mountpoint_is_detected(env, tmp_path): # Ausgefallenes NAS: Mountpunkt existiert, ist aber leer. - env.setenv("MINDNET_VAULT_ROOT", str(_vault(tmp_path, with_sentinel=False))) + env.setenv("MINDNET_VAULT_ROOT", str(_vault(tmp_path, with_content=False))) + with pytest.raises(ep.PreflightError, match="leer"): + ep.check_vault() + + +def test_vault_needs_no_specific_file_by_default(env, tmp_path): + # Wie systemd: jeder Vault-Aufbau ist zulässig (vault_master hat kein _system/). + env.setenv("MINDNET_VAULT_ROOT", str(_vault(tmp_path))) + env.setattr(ep, "_is_read_only_mount", lambda path: True) + ep.check_vault() + + +def test_vault_optional_sentinel_is_enforced(env, tmp_path): + env.setenv("MINDNET_VAULT_ROOT", str(_vault(tmp_path))) + env.setenv("MINDNET_VAULT_SENTINEL", "_system/dictionary/edge_vocabulary.md") with pytest.raises(ep.PreflightError, match="Sentinel"): ep.check_vault()