Files
mindnet/docs/05_Development/05_docker_migration_plan.md
T
LarsandClaude Opus 5.5 8f9f83aa79 Add reachability checks and develop/main container pipeline (inactive)
- 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>
2026-10-28 16:01:37 +01:00

11 KiB
Raw Blame History

doc_type, audience, scope, status, version, context
doc_type audience scope status version context
development_plan developer, devops docker_migration, release_gates, test_baseline, privacy_gateway draft 0.1.0 Migrationsplan Mindnet → Container (Dev/Prod) mit Freigabe-Gates, Testbaseline und Anforderungen an das Privacy Gateway.

Migrationsplan: Containerisierung

Stand: 28.10.2026. Betriebsdetails: Container-Betrieb. Die Review-Befunde R1–R9 stehen in 05_review_2026-09-25.md auf dem Branch codex/privacy-gateway. Der Link funktioniert erst, wenn beide Stände in develop zusammengeführt sind.

1. Rahmenbedingungen (entschieden)

  • Ziel-Host bleibt vorerst llm-node; nichts ist auf diesen Host oder auf lokale Python-Umgebungen zugeschnitten.
  • Ollama und GLiNER sind gemeinsame Dienste pro Host. Dev und Prod haben getrennte Konfiguration, Volumes und Compose-Projekte.
  • Die produktive Qdrant-Instanz bleibt unverändert; Dev hat eine eigene Instanz.
  • Embeddings: nomic-embed-text, 768 Dimensionen. Ein Rückfall auf MiniLM/384 wird technisch verhindert.
  • Vault vom NAS, nur lesend. Dev bekommt Testdaten. Prod-Schreibzugriff bleibt gesperrt, bis R2 behoben ist.
  • Containerisierung und Privacy Gateway sind getrennt. Keine echten Vault-Inhalte an Cloud-Anbieter.

2. Befunde aus Phase 0

Befund Auswirkung
Gitea-Repo Lars/mindnet ist öffentlich (private: false, anonymes git ls-remote möglich) Push der Gateway-Arbeit nicht durchgeführt. Sicherung nur lokal (Commits + Bundle).
Push auf main löst .gitea/workflows/deploy.yml aus: rsync --delete von app scripts schemas docker tests config … nach /home/llmadmin/mindnet plus Neustart Jeder Merge nach main ist ein Produktions-Deploy. Container-Dateien liegen deshalb in deploy/ (nicht synchronisiert).
config/prod.env ist versioniert; Key-Felder enthalten in allen Ständen nur Platzhalter (Länge 9/12) Kein Leak. Datei bleibt ungenutzt; das Image schließt config/*.env aus.
MiniLM: app/embeddings.py und embed_router sind nicht eingebunden. docker/embeddings.Dockerfile kopiert das nicht mehr existierende app/embed_server.py. mindnet-embed läuft laut Handbuch auf llm-node Nicht entfernt. Abschaltung erst nach Prüfung auf llm-node (Gate G2).
qdrant.py fällt ohne VECTOR_DIM auf 384 zurück; IngestionProcessor legt Collections beim Start an Preflight erzwingt VECTOR_DIM=768.
Ohne Cloud-Keys ruft der stabile Code Ollama mit Cloud-Modell-IDs auf (R4) Chat lokal nur über Fallback-Kette; langsamer, aber ohne Egress.

3. Branches

Branch Basis Inhalt Ort
main — Produktion (systemd, Auto-Deploy) Gitea
develop origin/main (0d61a9e) Integrationszweig nach Kansho-Muster; Push deployt Dev, sobald deploy-dev.yml aktiv ist (G3) nur lokal
feature/containerization develop Phase 1 nur lokal
codex/privacy-gateway origin/main Gateway (2 Commits), unverändert nur lokal + Bundle
origin/SectionType origin/main WP-26; R3 offen Gitea

Reihenfolge: feature/containerization → develop. Das Gateway folgt erst nach der Docker-Anpassung aus Abschnitt 6 und als eigener Merge. Ein Konflikt mit dem Gateway-Branch ist nicht zu erwarten: deploy/, .dockerignore und die neuen Docs/Tests sind neu, .gitignore nur auf dem Gateway-Branch.

4. Testbaseline (17 bestehende Fehler, kategorisiert)

Gleiches Ergebnis mit lokaler venv und mit einer frischen venv aus deploy/requirements.lock: 12 failed, 5 errors. Keiner davon wurde deaktiviert.

Kategorie Tests Ursache Empfehlung
A – echter Produktfehler test_query_text_embed_unit::test_query_with_text app/routers/query.py:28 übergibt log_search(req, res); Signatur ist (query_id, query_text, results, …). Das Suchprotokoll für /query schlägt im Hintergrund fehl. Aufruf korrigieren (eigener Fix).
A – echter Produktfehler test_query_unit::test_query_hybrid_with_monkeypatch, test_retriever_basic::test_hybrid_retrieve_basic retriever.py:401 loggt req.query[:100]; bei reiner Vektor-Abfrage ist query=None → TypeError → HTTP 500. Logging None-sicher machen (eigener Fix).
B – veralteter Test (API umgebaut) test_final_wp15_validation, test_smart_chunking_integration, test_wp15_final (Collection-Error) from app.core import chunker – Modul existiert nicht mehr (jetzt app/core/chunking/). Auf neue API portieren oder bewusst archivieren.
B test_WP22_intelligence (4) EdgeRegistry(vault_root=…) – Parameter entfernt. Portieren.
B test_dialog_full_flow (2) save_note() verlangt background_tasks. Portieren.
C – fachlich klären test_type_registry::test_defaults_when_missing Test erwartet chunk_profile, Code liefert chunking_profile. Entscheiden, welcher Schlüssel gilt.
C test_retriever_edges::test_hybrid_retrieve_uses_edge_scores Erwartetes Ranking (note:2 vor note:1) tritt nicht ein. Prüfen, ob Edge-Scoring regressiert oder Erwartung veraltet ist.
D – braucht Infrastruktur / falsch gepatcht test_graph_unit::test_graph_neighbors Patcht nicht mehr die tatsächlich aufgerufene Funktion → echte Qdrant-Verbindung. Patch korrigieren; danach Unit-Test ohne Qdrant.
E – kein pytest-Test test_interview_intent::test_intent, test_wp06_decision::test_decision_engine Funktionsparameter message/query werden als Fixture interpretiert; manuelle Skripte gegen laufende Dienste. Nach scripts/ verschieben oder als Integrationstest mit Marker.

Für eine CI-Pipeline wie bei Kansho: zuerst A beheben, B/D portieren, C entscheiden, E umziehen. Danach ist die Baseline ehrlich grün. Bis dahin läuft die volle Suite in deploy/deploy.sh nur informativ; blockierend sind die Container-Tests. Nächster Schritt dafür: eine explizite Liste dieser 17 Fälle, gegen die neue Fehler den Deploy stoppen.

5. Freigabe-Gates

Gate Inhalt Wer
G0 Repo Lars/mindnet auf privat stellen (oder anderes privates Ziel benennen); danach Push von codex/privacy-gateway, develop, feature/containerization Lars
G1 Review dieses Stands; Merge feature/containerization → develop Lars
G2 Nur lesende Prüfungen auf llm-node: Docker-/Compose-Version, Port-Bindung Qdrant/Ollama (ss -ltnp), docker ps (läuft mindnet-embed?), pip freeze der Prod-venv, NAS-Mount (findmnt), Lesbarkeit für UID 10001 Freigabe Lars
G3 Dev-Stack auf llm-node bauen und starten (eigene Qdrant, Testdaten-Vault), preflight --live; danach Aktivierung von deploy/gitea-workflows/deploy-dev.yml (jeder Push auf develop deployt Dev) Freigabe Lars
G4 Prod-Container parallel zu systemd starten (nur lesend auf Prod-Qdrant, Vault ro), Vergleich der Antworten Freigabe Lars
G5 Umschaltung Prod auf Container; systemd 2–3 Wochen als Rückfallebene; im selben Commit deploy-prod.yml aktivieren und .gitea/workflows/deploy.yml entfernen Freigabe Lars; Voraussetzung R2, falls Schreibzugriff nötig

R2 – Pfadsicherheit beim Speichern (Pflicht vor beschreibbarem Vault)

create_from_text setzt folder/filename per os.path.join zusammen und schreibt ungeprüft. Die Container verhindern das derzeit nur über den schreibgeschützten Mount. Vor jedem beschreibbaren Prod-Vault: aufgelösten Zielpfad gegen den aufgelösten Vault prüfen, absolute Pfade und .. ablehnen, Symlinks berücksichtigen, Überschreibregeln festlegen, Tests ergänzen. Zusätzlich gehört vor /ingest/* eine Zugriffsgrenze (Authentisierung).

R3 – Section-Types (Pflichtkorrektur vor Integration von SectionType)

_propagate_section_type_backwards gruppiert fest auf H2 und überträgt den ersten Typ auf alle Blöcke. Zwei H3-Abschnitte mit unterschiedlichen Typen erhalten denselben Typ, und der H2-Elterntext wird umtypisiert (Reproduktion im Review). Gesonderte Korrektur auf dem SectionType-Branch mit verschachteltem Regressionstest. Erst danach Merge nach develop. In diesem Arbeitspaket bewusst nicht behoben.

6. Phase 2: Privacy Gateway im Container (Anforderungen)

Gilt für die spätere Anpassung von require_local_endpoint und LocalDetector. Grundsatz bleibt fail-closed.

Zielverbindungen. Eine Host-Allowlist mit einmaliger DNS-Auflösung reicht nicht. Zwischen Prüfung und Verbindung kann der Name auf eine andere Adresse zeigen (DNS-Rebinding), und Redirects oder Proxies können das Ziel wechseln. Anforderungen:

  1. Allowlist erlaubter Dienste mit Name, Port und Schema (ollama:11434, gliner:8090), keine Wildcards.
  2. Auflösung pro Verbindung; alle aufgelösten Adressen müssen in erlaubten Netzen liegen (bevorzugt im Compose-Subnetz statt pauschal RFC1918). Sonst Abbruch.
  3. Verbinden auf die geprüfte IP (Pinning über eigenen httpx-Transport bzw. Resolver), Host-Header bzw. SNI bleibt der Name. Danach die tatsächliche Gegenstelle des Sockets (getpeername) gegen die geprüfte IP vergleichen.
  4. follow_redirects=False, trust_env=False (keine Proxies), keine URL-Credentials; Antwort-Redirects sind Fehler.
  5. Netzwerkseitig zusätzlich absichern: Detector und Ollama in einem internal: true-Netz ohne Internetzugang. Ausgehender Cloud-Verkehr nur aus dem API-Container und perspektivisch über einen Egress-Proxy mit Provider-Allowlist.
  6. Tests: Rebinding-Simulation (zweite Auflösung liefert öffentliche IP), Redirect-Antwort, Proxy-Variablen gesetzt, IPv6-mapped-IPv4, Link-Local/Metadaten-IP (169.254.169.254).

Ausfall der Personenerkennung. Cloud-Aufrufe werden blockiert (PrivacyError, kein Fallback). Das ist im Gateway-Branch bereits so umgesetzt.

Wiederholungsmechanismus für die Ingestion (Entwurf). Bisher bekommt eine Notiz status: error, wenn die Kantenvalidierung an einem PrivacyError scheitert. Ziel ist eine nachvollziehbare, nicht stille Wiederholung:

  1. Kein Teil-Commit: Note, Chunks und explizite Kanten werden geschrieben. Kandidaten-Kanten, deren Validierung nicht möglich war, werden nicht verworfen und nicht als validiert markiert. Sie bleiben mit validation_state: pending und einem Reason-Code (local_detection_failed, local_endpoint_required, …) erhalten.
  2. Persistente Warteschlange im data-Volume (z. B. SQLite data/ingest_retry.db), Schlüssel (note_id, content_hash): Versuchszähler, next_attempt_at mit exponentiellem Backoff, letzter Reason-Code. Keine Inhalte, nur Referenzen.
  3. Idempotenz: Ändert sich die Notiz, wird der alte Eintrag durch den neuen Hash ersetzt. Wiederholung verarbeitet nur die offenen Kandidaten.
  4. Auslösung: Zunächst manuell (CLI-Skript bzw. Admin-Endpoint). Ein automatischer Scheduler erst nach gesonderter Freigabe, weil er gegen Produktivdaten läuft.
  5. Sichtbarkeit: /admin/stats und Healthcheck-Details melden Anzahl pending/failed; nach max_attempts Status failed mit Reason-Code, nie stilles Verwerfen.
  6. Tests: Detector-Ausfall während der Ingestion → Note vorhanden, Kandidaten pending, Queue-Eintrag. Erneuter Lauf mit verfügbarem Detector → validiert, Eintrag entfernt.

7. Nächste Schritte

  1. G0: Repo-Sichtbarkeit klären.
  2. G1: Review/Merge von feature/containerization nach develop.
  3. G2: lesende Prüfungen auf llm-node (Kommandos in Container-Betrieb §4–5).
  4. Fix-Pakete A (query/retriever) und R3 separat; Gateway-Anpassung nach Abschnitt 6.