- preflight --live: Ollama/Qdrant reachable from the container, required Ollama models present, 768 dimensions; clear abort instead of traceback. Static check rejects unset or container-local service URLs. - deploy/smoke.py: non-writing post-start check via published ports. - deploy/deploy.sh: test (no network), build, preflight, up --wait, smoke; prod rolls back to the last good image tag. - Workflow templates deploy-dev.yml (push develop) and deploy-prod.yml (push main) following the Kansho pattern; not under .gitea/workflows. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
247 lines
11 KiB
Python
247 lines
11 KiB
Python
"""
|
|
FILE: deploy/entrypoint.py
|
|
DESCRIPTION: Container-Entrypoint für Mindnet (API, UI, Preflight).
|
|
Prüft vor dem Start alle Annahmen, deren Verletzung still Daten
|
|
verfälschen oder Inhalte nach außen geben würde, und bricht sonst ab:
|
|
- Vektor-Dimension und Embedding-Modell (768 / nomic-embed-text)
|
|
- explizite Umgebung und Collection-Präfix (Dev nie auf Prod-Präfix)
|
|
- Vault: vorhanden, Sentinel lesbar (NAS gemountet), schreibgeschützt
|
|
- kein Cloud-LLM-Key ohne ausdrückliche Freigabe
|
|
- Dienst-URLs gesetzt und nicht auf den Container selbst (localhost)
|
|
Mit 'preflight --live' zusätzlich (nur lesend): Ollama und Qdrant
|
|
erreichbar, benötigte Modelle vorhanden, Dimensionen stimmen.
|
|
VERSION: 1.1.0
|
|
STATUS: Active
|
|
USAGE: entrypoint.py api | ui | preflight [--live]
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
import os
|
|
import sys
|
|
import urllib.error
|
|
import urllib.parse
|
|
import urllib.request
|
|
from pathlib import Path
|
|
|
|
import yaml
|
|
|
|
CLOUD_KEYS = ("OPENROUTER_API_KEY", "GOOGLE_API_KEY")
|
|
CLOUD_EGRESS_ACK = "MINDNET_ALLOW_CLOUD_EGRESS"
|
|
SERVICE_URLS = ("MINDNET_OLLAMA_URL", "QDRANT_URL")
|
|
LOOPBACK_HOSTS = {"localhost", "127.0.0.1", "::1", "0.0.0.0"}
|
|
|
|
|
|
class PreflightError(RuntimeError):
|
|
pass
|
|
|
|
|
|
def _flag(name: str, default: str) -> bool:
|
|
return os.getenv(name, default).strip().lower() == "true"
|
|
|
|
|
|
def check_environment() -> str:
|
|
env = os.getenv("MINDNET_ENV", "").strip()
|
|
if env not in {"dev", "prod"}:
|
|
raise PreflightError("MINDNET_ENV muss 'dev' oder 'prod' sein.")
|
|
prefix = os.getenv("COLLECTION_PREFIX", "").strip()
|
|
if not prefix:
|
|
# Ohne Präfix fällt die App still auf 'mindnet' (= Produktion) zurück.
|
|
raise PreflightError("COLLECTION_PREFIX muss explizit gesetzt sein.")
|
|
if env == "dev" and not prefix.endswith("_dev"):
|
|
raise PreflightError(f"Dev-Umgebung verlangt ein Präfix mit Suffix '_dev' (ist: '{prefix}').")
|
|
if env == "prod" and prefix.endswith("_dev"):
|
|
raise PreflightError(f"Prod-Umgebung mit Dev-Präfix '{prefix}'.")
|
|
return env
|
|
|
|
|
|
def _load_profiles(profiles_path: str | None = None) -> dict:
|
|
# Gleicher Pfad wie in der App (Settings kennt keinen Override dafür).
|
|
path = Path(profiles_path or "config/llm_profiles.yaml")
|
|
try:
|
|
data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
|
|
except (OSError, yaml.YAMLError) as e:
|
|
raise PreflightError(f"LLM-Profile nicht lesbar: {path} ({type(e).__name__}).") from None
|
|
return data.get("profiles") or {}
|
|
|
|
|
|
def check_embeddings(profiles_path: str | None = None) -> None:
|
|
expected_dim = int(os.getenv("MINDNET_EXPECTED_VECTOR_DIM", "768"))
|
|
expected_model = os.getenv("MINDNET_EXPECTED_EMBEDDING_MODEL", "nomic-embed-text")
|
|
|
|
# qdrant.py fällt ohne VECTOR_DIM auf 384 (MiniLM) zurück.
|
|
dim = os.getenv("VECTOR_DIM", "").strip()
|
|
if dim != str(expected_dim):
|
|
raise PreflightError(f"VECTOR_DIM muss {expected_dim} sein (ist: '{dim or 'nicht gesetzt'}').")
|
|
|
|
env_model = os.getenv("MINDNET_EMBEDDING_MODEL", "").strip()
|
|
if env_model and env_model != expected_model:
|
|
raise PreflightError(f"MINDNET_EMBEDDING_MODEL='{env_model}' weicht von '{expected_model}' ab.")
|
|
|
|
# Das Profil hat Vorrang vor der Umgebung; fehlt es, fällt der Client auf das Chat-Modell zurück.
|
|
profile = _load_profiles(profiles_path).get("embedding_expert") or {}
|
|
if profile.get("provider", "ollama") != "ollama" or profile.get("model") != expected_model:
|
|
raise PreflightError(f"Profil embedding_expert muss ollama/{expected_model} sein.")
|
|
if int(profile.get("dimensions") or 0) != expected_dim:
|
|
raise PreflightError(f"Profil embedding_expert muss dimensions={expected_dim} haben.")
|
|
|
|
|
|
def check_cloud_egress() -> None:
|
|
configured = [k for k in CLOUD_KEYS if os.getenv(k, "").strip()]
|
|
if configured and not _flag(CLOUD_EGRESS_ACK, "false"):
|
|
# Ohne Privacy Gateway würden Vault-Inhalte unmaskiert an Cloud-Provider gehen.
|
|
raise PreflightError(
|
|
f"Cloud-Keys gesetzt ({', '.join(configured)}), aber {CLOUD_EGRESS_ACK}=true fehlt. "
|
|
"Ohne Privacy Gateway gehen Vault-Inhalte unmaskiert an den Provider."
|
|
)
|
|
|
|
|
|
def _is_read_only_mount(path: Path) -> bool:
|
|
if not hasattr(os, "statvfs"):
|
|
return False # nicht prüfbar -> als beschreibbar behandeln (fail closed)
|
|
return bool(os.statvfs(path).f_flag & os.ST_RDONLY)
|
|
|
|
|
|
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():
|
|
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")
|
|
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).")
|
|
|
|
|
|
def check_service_urls() -> None:
|
|
for name in SERVICE_URLS:
|
|
url = os.getenv(name, "").strip()
|
|
if not url:
|
|
# Die App fiele sonst still auf http://127.0.0.1:... zurück, also auf den Container selbst.
|
|
raise PreflightError(f"{name} muss explizit gesetzt sein.")
|
|
if urllib.parse.urlsplit(url).hostname in LOOPBACK_HOSTS:
|
|
raise PreflightError(
|
|
f"{name}='{url}' zeigt im Container auf den Container selbst. "
|
|
"Host-Dienste über host.docker.internal ansprechen."
|
|
)
|
|
|
|
|
|
def _fetch_json(url: str, payload: dict | None = None, headers: dict | None = None, timeout: float = 10):
|
|
"""GET (oder POST mit payload). Netzwerkfehler werden zu PreflightError, HTTPError bleibt erhalten."""
|
|
req = urllib.request.Request(
|
|
url, method="POST" if payload is not None else "GET",
|
|
data=json.dumps(payload).encode() if payload is not None else None,
|
|
headers={"Content-Type": "application/json", **(headers or {})},
|
|
)
|
|
try:
|
|
with urllib.request.urlopen(req, timeout=timeout) as res:
|
|
return json.load(res)
|
|
except urllib.error.HTTPError:
|
|
raise
|
|
except (urllib.error.URLError, OSError) as e:
|
|
hint = ""
|
|
if urllib.parse.urlsplit(url).hostname == "host.docker.internal":
|
|
hint = " Lauscht der Dienst auf dem Host nur an 127.0.0.1?"
|
|
raise PreflightError(f"{url} nicht erreichbar ({getattr(e, 'reason', e)}).{hint}") from None
|
|
except ValueError:
|
|
raise PreflightError(f"{url} liefert kein JSON.") from None
|
|
|
|
|
|
def required_ollama_models(profiles_path: str | None = None) -> set[str]:
|
|
models = {p["model"] for p in _load_profiles(profiles_path).values()
|
|
if isinstance(p, dict) and p.get("provider") == "ollama" and p.get("model")}
|
|
# Lokales Chat-Modell: Endpunkt der Fallback-Kette ohne Cloud-Keys (Review R4).
|
|
if os.getenv("MINDNET_LLM_MODEL", "").strip():
|
|
models.add(os.environ["MINDNET_LLM_MODEL"].strip())
|
|
return models
|
|
|
|
|
|
def _has_model(required: str, available: set[str]) -> bool:
|
|
return required in available or (":" not in required and f"{required}:latest" in available)
|
|
|
|
|
|
def check_live(profiles_path: str | None = None) -> None:
|
|
"""Laufzeitprüfung (nur lesend): Erreichbarkeit, Modelle, Embedding- und Collection-Dimension."""
|
|
expected_dim = int(os.getenv("MINDNET_EXPECTED_VECTOR_DIM", "768"))
|
|
ollama = os.getenv("MINDNET_OLLAMA_URL", "").rstrip("/")
|
|
model = os.getenv("MINDNET_EXPECTED_EMBEDDING_MODEL", "nomic-embed-text")
|
|
|
|
tags = _fetch_json(f"{ollama}/api/tags")
|
|
available = {m.get("name") for m in tags.get("models") or []}
|
|
missing = sorted(m for m in required_ollama_models(profiles_path) if not _has_model(m, available))
|
|
if missing:
|
|
raise PreflightError(f"Ollama ({ollama}) fehlen die Modelle: {', '.join(missing)}.")
|
|
|
|
embedding = _fetch_json(f"{ollama}/api/embeddings", {"model": model, "prompt": "preflight"}, timeout=30)
|
|
got = len(embedding.get("embedding") or [])
|
|
if got != expected_dim:
|
|
raise PreflightError(f"Ollama liefert {got} Dimensionen für '{model}', erwartet {expected_dim}.")
|
|
print(f"preflight: Ollama erreichbar ({ollama}), Modelle vorhanden, '{model}' = {got} Dimensionen.")
|
|
|
|
qdrant = os.getenv("QDRANT_URL", "").rstrip("/")
|
|
headers = {"api-key": os.environ["QDRANT_API_KEY"]} if os.getenv("QDRANT_API_KEY") else {}
|
|
try:
|
|
_fetch_json(f"{qdrant}/collections", headers=headers)
|
|
except urllib.error.HTTPError as e:
|
|
raise PreflightError(f"Qdrant ({qdrant}) antwortet mit HTTP {e.code}.") from None
|
|
prefix = os.getenv("COLLECTION_PREFIX", "")
|
|
for suffix in ("notes", "chunks"):
|
|
name = f"{prefix}_{suffix}"
|
|
try:
|
|
info = _fetch_json(f"{qdrant}/collections/{name}", headers=headers)
|
|
except urllib.error.HTTPError as e:
|
|
if e.code == 404:
|
|
print(f"preflight: Collection '{name}' existiert noch nicht.")
|
|
continue
|
|
raise PreflightError(f"Qdrant-Collection '{name}': HTTP {e.code}.") from None
|
|
vectors = info["result"]["config"]["params"]["vectors"]
|
|
sizes = [vectors["size"]] if "size" in vectors else [v["size"] for v in vectors.values()]
|
|
if any(s != expected_dim for s in sizes):
|
|
raise PreflightError(f"Collection '{name}' hat Dimension {sizes}, erwartet {expected_dim}.")
|
|
print(f"preflight: Qdrant erreichbar ({qdrant}), Collections '{prefix}_*' passen.")
|
|
|
|
|
|
def run_checks(mode: str) -> None:
|
|
check_environment()
|
|
check_embeddings()
|
|
check_cloud_egress()
|
|
if mode in {"api", "preflight"}:
|
|
check_service_urls()
|
|
check_vault()
|
|
|
|
|
|
COMMANDS = {
|
|
"api": ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "1"],
|
|
"ui": ["streamlit", "run", "app/frontend/ui.py", "--server.address", "0.0.0.0",
|
|
"--server.port", "8501", "--server.headless", "true", "--browser.gatherUsageStats", "false"],
|
|
}
|
|
|
|
|
|
def main(argv: list[str]) -> int:
|
|
mode = argv[1] if len(argv) > 1 else "api"
|
|
if mode not in {*COMMANDS, "preflight"}:
|
|
print(f"Unbekannter Modus '{mode}'. Erlaubt: api, ui, preflight [--live]", file=sys.stderr)
|
|
return 2
|
|
try:
|
|
run_checks(mode)
|
|
if mode == "preflight" and "--live" in argv:
|
|
check_live()
|
|
except PreflightError as e:
|
|
print(f"preflight: ABBRUCH: {e}", file=sys.stderr)
|
|
return 1
|
|
if mode == "preflight":
|
|
print("preflight: OK")
|
|
return 0
|
|
os.execvp(COMMANDS[mode][0], COMMANDS[mode])
|
|
return 0 # nicht erreichbar
|
|
|
|
|
|
if __name__ == "__main__":
|
|
sys.exit(main(sys.argv))
|