- .gitea/workflows/deploy-dev.yml: prepares the host (synthetic test vault, dev.env from the example on first run, never overwritten), then runs deploy/deploy.sh dev. Prod workflow stays an inactive template. - deploy/testvault: synthetic notes from scripts/make_test_vault.py plus synthetic edge_vocabulary.md/graph_schema.md (vault sentinel). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
11 KiB
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 (G3) | Gitea |
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; .gitea/workflows/deploy-dev.yml aktiv, jeder Push auf develop deployt Dev |
freigegeben 28.10.2026 |
| 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:
- Allowlist erlaubter Dienste mit Name, Port und Schema (
ollama:11434,gliner:8090), keine Wildcards. - Auflösung pro Verbindung; alle aufgelösten Adressen müssen in erlaubten Netzen liegen (bevorzugt im Compose-Subnetz statt pauschal RFC1918). Sonst Abbruch.
- 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. follow_redirects=False,trust_env=False(keine Proxies), keine URL-Credentials; Antwort-Redirects sind Fehler.- 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. - 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:
- 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: pendingund einem Reason-Code (local_detection_failed,local_endpoint_required, …) erhalten. - Persistente Warteschlange im
data-Volume (z. B. SQLitedata/ingest_retry.db), Schlüssel(note_id, content_hash): Versuchszähler,next_attempt_atmit exponentiellem Backoff, letzter Reason-Code. Keine Inhalte, nur Referenzen. - Idempotenz: Ändert sich die Notiz, wird der alte Eintrag durch den neuen Hash ersetzt. Wiederholung verarbeitet nur die offenen Kandidaten.
- Auslösung: Zunächst manuell (CLI-Skript bzw. Admin-Endpoint). Ein automatischer Scheduler erst nach gesonderter Freigabe, weil er gegen Produktivdaten läuft.
- Sichtbarkeit:
/admin/statsund Healthcheck-Details melden Anzahlpending/failed; nachmax_attemptsStatusfailedmit Reason-Code, nie stilles Verwerfen. - 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
- G0: Repo-Sichtbarkeit klären.
- G1: Review/Merge von
feature/containerizationnachdevelop. - G2: lesende Prüfungen auf llm-node (Kommandos in Container-Betrieb §4–5).
- Fix-Pakete A (query/retriever) und R3 separat; Gateway-Anpassung nach Abschnitt 6.