--- doc_type: development_plan audience: developer, devops scope: docker_migration, release_gates, test_baseline, privacy_gateway status: draft version: 0.1.0 context: "Migrationsplan Mindnet → Container (Dev/Prod) mit Freigabe-Gates, Testbaseline und Anforderungen an das Privacy Gateway." --- # Migrationsplan: Containerisierung Stand: 28.10.2026. Betriebsdetails: [Container-Betrieb](../04_Operations/04_docker_deployment.md). 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](../04_Operations/04_docker_deployment.md)). 4. Fix-Pakete A (query/retriever) und R3 separat; Gateway-Anpassung nach Abschnitt 6.