Prepare containerized dev/prod deployment (inactive)

Add a Docker image and separate Compose projects for development and
production, based on the stable main behaviour without the privacy
gateway. Nothing is wired into the existing systemd deploy workflow.

- One non-root image (api | ui | preflight), base image pinned by
  digest, dependencies from a hash-locked universal lock without torch
  and sentence-transformers (MiniLM is not on the runtime path)
- Preflight aborts on: VECTOR_DIM != 768 or non-nomic embedding
  profile, implicit or cross-env collection prefix, cloud keys without
  explicit egress acknowledgement, missing/empty or writable vault mount
- Vault is a read-only NAS bind mount without host-path autocreation;
  healthcheck turns unhealthy when the vault sentinel disappears
- Dev runs its own Qdrant; prod reuses the existing host instance
- API published on loopback only; read-only rootfs, cap_drop ALL,
  no-new-privileges
- Dev workflow kept as an inactive template outside .gitea/workflows
- Docs: operations guide and migration plan with release gates, test
  baseline classification, R2/R3 and privacy gateway requirements

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
LarsandClaude Opus 5.5 committed 2026-10-28 14:33:18 +01:00
1 parent 0d61a9e191
commit 7a225ba2b6
18 files changed
+2864

No files matched your search

+179
View File
@@ -0,0 +1,179 @@
"""
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
VERSION: 1.0.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.request
from pathlib import Path
import yaml
CLOUD_KEYS = ("OPENROUTER_API_KEY", "GOOGLE_API_KEY")
CLOUD_EGRESS_ACK = "MINDNET_ALLOW_CLOUD_EGRESS"
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 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.
# 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
profile = (data.get("profiles") or {}).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_live() -> None:
"""Optionale Laufzeitprüfung: tatsächliche Embedding- und Collection-Dimension (nur lesend)."""
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")
req = urllib.request.Request(
f"{ollama}/api/embeddings", method="POST",
data=json.dumps({"model": model, "prompt": "preflight"}).encode(),
headers={"Content-Type": "application/json"},
)
with urllib.request.urlopen(req, timeout=30) as res:
got = len(json.load(res).get("embedding") or [])
if got != expected_dim:
raise PreflightError(f"Ollama liefert {got} Dimensionen für '{model}', erwartet {expected_dim}.")
qdrant = os.getenv("QDRANT_URL", "").rstrip("/")
prefix = os.getenv("COLLECTION_PREFIX", "")
for suffix in ("notes", "chunks"):
name = f"{prefix}_{suffix}"
try:
with urllib.request.urlopen(f"{qdrant}/collections/{name}", timeout=10) as res:
vectors = json.load(res)["result"]["config"]["params"]["vectors"]
except urllib.error.HTTPError as e:
if e.code == 404:
print(f"preflight: Collection '{name}' existiert noch nicht.")
continue
raise
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}.")
def run_checks(mode: str) -> None:
check_environment()
check_embeddings()
check_cloud_egress()
if mode in {"api", "preflight"}:
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))