Files
mindnet/docs/04_Operations/04_docker_deployment.md
T
LarsandClaude Opus 5.5 7a225ba2b6 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>
2026-10-28 14:33:18 +01:00

9.7 KiB

doc_type, audience, scope, status, version, context
doc_type audience scope status version context
operations_manual devops, deployment_engineer docker, compose, container_security, nas_mount draft 0.1.0 Container-Betrieb von Mindnet (Dev/Prod) auf llm-node. Vorbereitung, noch keine produktive Umschaltung.

Container-Betrieb (Docker Compose)

Stand: 28.10.2026. Status: vorbereitet, nicht aktiv. Produktion läuft unverändert über systemd und .gitea/workflows/deploy.yml (siehe Deployment Guide). Der Containerstand basiert auf dem stabilen main-Verhalten ohne Privacy Gateway.

1. Überblick

Dev Prod
Compose-Datei deploy/compose.dev.yml deploy/compose.prod.yml
Projektname mindnet-dev mindnet-prod
API (nur 127.0.0.1) 8012 8011
UI (Bind-Adresse konfigurierbar) 8512 8511
Qdrant eigener Container qdrant, Volume mindnet-dev_qdrant bestehende Host-Instanz, unverändert
Collection-Präfix mindnet_dev (fest) mindnet (env-Datei, von Preflight geprüft)
Vault Testdaten, nur lesend NAS-Vault, nur lesend
Ollama gemeinsamer Host-Dienst gemeinsamer Host-Dienst

Die Ports kollidieren weder untereinander noch mit systemd (8001/8002/8501/8502). Dev und Prod können später parallel zu den systemd-Diensten laufen, was einen Vergleich vor der Umschaltung erlaubt.

Alle Dateien liegen unter deploy/. Dieser Ordner gehört nicht zu DEPLOY_DIRS des bestehenden Workflows und wird daher nicht automatisch auf den Server synchronisiert. Der alte Ordner docker/ (MiniLM-Embed-Dienst, Port 8990) bleibt unverändert, siehe Abschnitt 8.

2. Image

deploy/Dockerfile, Build-Kontext ist das Repository-Root:

docker build -f deploy/Dockerfile -t mindnet:$(git rev-parse --short HEAD) .
  • Ein Image, drei Modi: api (uvicorn, 1 Worker), ui (Streamlit), preflight [--live].
  • Reproduzierbar: Basis python:3.12-slim-bookworm per Digest; Abhängigkeiten aus deploy/requirements.lock mit --require-hashes.
  • Ohne torch/sentence-transformers: Der MiniLM-Pfad (app/embeddings.py, embed_router) ist im Laufzeitcode nicht eingebunden. Embeddings kommen ausschließlich von Ollama.
  • Nicht-root: Nutzer mindnet (UID 10001). Code und Config gehören root und sind nur lesbar.
  • Build-Kontext als Allowlist (/.dockerignore): Nur app/, config/, scripts/, tests/ und deploy/ gelangen in den Build-Kontext. Ausgeschlossen bleiben .env-Dateien, config/*.env, Vault, Logs und venvs.
  • Test-Target: docker build --target test … installiert zusätzlich pytest.

Lock neu erzeugen

Nur bewusst, z. B. bei Sicherheitsupdates, und danach die Testsuite laufen lassen:

cd deploy
uv pip compile requirements.in --universal --python-version 3.12 \
  --exclude-newer <ISO-Datum> --generate-hashes --no-header -o requirements.lock
uv pip compile requirements-test.in --universal --python-version 3.12 \
  --exclude-newer <ISO-Datum> --generate-hashes --no-header -o requirements-test.lock

Der aktuelle Lock wurde mit --exclude-newer 2026-01-22 erzeugt, also dem Stand nach dem letzten main-Commit, den das systemd-Deploy damals per pip install gezogen haben dürfte. Offen: Abgleich mit pip freeze der produktiven venv auf llm-node (nur lesend, erfordert Freigabe).

3. Preflight (Abbruch statt stiller Fehler)

deploy/entrypoint.py prüft vor jedem Start und bricht mit Exit-Code 1 ab, wenn:

Prüfung Schützt vor
MINDNET_ENV ∈ {dev, prod}; COLLECTION_PREFIX explizit; Dev nur *_dev, Prod nie *_dev Dev schreibt in Prod-Collections; stiller Default mindnet
VECTOR_DIM == 768, Profil embedding_expert = ollama/nomic-embed-text/768, kein abweichendes MINDNET_EMBEDDING_MODEL stiller Rückfall auf 384 (MiniLM) in qdrant.py bzw. auf das Chat-Modell als Embedding
Cloud-Key gesetzt ohne MINDNET_ALLOW_CLOUD_EGRESS=true unmaskierte Vault-Inhalte an OpenRouter/Gemini
Vault fehlt, Sentinel nicht lesbar, Mount nicht ro (statvfs ST_RDONLY) Arbeiten auf leerem NAS-Mountpunkt; Schreiben in den Vault (R2)

Die Werte für Umgebung, Dimension und Vault stehen in den Compose-Dateien unter environment und lassen sich nicht über die env-Datei überschreiben.

preflight --live prüft zusätzlich nur lesend die tatsächliche Ollama-Embedding-Länge und die Vektorgröße der Collections <prefix>_notes und <prefix>_chunks:

docker compose -f deploy/compose.dev.yml --env-file deploy/env/dev.env run --rm --no-deps api preflight --live

4. Vault auf dem NAS

  • Der Bind-Mount ist read_only: true, mit create_host_path: false (kein stilles Anlegen) und propagation: rslave. Ein später wieder eingehängtes NAS wird dadurch im Container sichtbar, sofern der Host-Mountpunkt shared ist.
  • Sentinel: Standard ist _system/dictionary/edge_vocabulary.md relativ zum Vault, einstellbar über MINDNET_VAULT_SENTINEL. Die Datei existiert im echten Vault bereits; am NAS muss also nichts angelegt werden. Ein Testdaten-Vault für Dev braucht sie ebenfalls.
  • NAS beim Start nicht verfügbar: Die API startet nicht. restart: unless-stopped versucht es mit Backoff weiter. Die UI hängt an der gesunden API.
  • NAS fällt im Betrieb aus: Der Healthcheck meldet die API als unhealthy. Lesende Abfragen gegen Qdrant laufen weiter. Speichern ist wegen des schreibgeschützten Mounts ohnehin ausgeschlossen. /ingest/save würde ohne ro den fehlenden Vault-Ordner per os.makedirs neu anlegen; genau das verhindert der Mount.
  • Berechtigungen: Der Container läuft als UID 10001. Der Vault muss für diese UID lesbar sein, z. B. über others: r-x oder eine passende Gruppe auf dem NAS-Export. Bei CIFS-Mounts gelten uid/gid/file_mode aus den Mount-Optionen des Hosts. Prüfen, ohne am NAS etwas zu ändern:
mountpoint <vault-pfad>; findmnt -o TARGET,SOURCE,FSTYPE,OPTIONS,PROPAGATION <vault-pfad>
sudo -u '#10001' test -r <vault-pfad>/_system/dictionary/edge_vocabulary.md && echo lesbar

5. Netzwerk und gemeinsame Dienste

Die Container erreichen Host-Dienste über host.docker.internal (host-gateway). Voraussetzung, vor dem ersten Start auf llm-node nur lesend zu prüfen:

ss -ltnp | grep -E ':(6333|11434)\b'    # Binden Qdrant/Ollama nur an 127.0.0.1?
docker inspect qdrant --format '{{json .HostConfig.PortBindings}}'

Sind Qdrant oder Ollama nur an 127.0.0.1 gebunden, ist der Host-Gateway nicht erreichbar. Lösungsmöglichkeiten, jede nur mit Freigabe: Ollama an die Bridge-Adresse binden (OLLAMA_HOST), den Prod-Container an das bestehende Docker-Netz von qdrant anhängen (externes Netz), oder network_mode: host für die API. Keine davon ist umgesetzt.

Die API hat keine Authentisierung und wird daher nur an 127.0.0.1 veröffentlicht. Die UI erreicht sie intern über http://api:8000. Für LAN-Zugriff auf die UI wird MINDNET_UI_BIND auf die LAN-IP des Hosts gesetzt.

6. Härtung

Für api und ui: read_only-Rootfs, tmpfs /tmp, cap_drop: ALL, no-new-privileges, init, pids_limit, mem_limit, rotierende json-Logs. Beschreibbar sind nur die Volumes logs (/app/logs) und data (/app/data). Die UI bindet data nur lesend ein.

7. Bedienung

cp deploy/env/dev.env.example deploy/env/dev.env   # ausfüllen; *.env ist git-ignoriert
docker compose -f deploy/compose.dev.yml --env-file deploy/env/dev.env build
docker compose -f deploy/compose.dev.yml --env-file deploy/env/dev.env run --rm --no-deps api preflight
docker compose -f deploy/compose.dev.yml --env-file deploy/env/dev.env up -d --wait

Dev-Daten aufbauen (nur Dev-Qdrant, Präfix fest mindnet_dev): Der Vault-Mount ist nur lesend; der Import liest die Dateien und schreibt ausschließlich in Qdrant.

DEV="docker compose -f deploy/compose.dev.yml --env-file deploy/env/dev.env"
$DEV run --rm --no-deps api preflight && \
$DEV run --rm --entrypoint python api -m scripts.import_markdown --vault /vault --prefix mindnet_dev --apply

Hinweis: Ein Befehl hinter run ersetzt nur CMD; entrypoint.py lehnt unbekannte Modi ab. Für Skripte wird der Entrypoint deshalb mit --entrypoint python ersetzt. Der Preflight muss dann vorher separat laufen, wie oben gezeigt. Die übrigen Prüfungen bleiben wirksam: fester Präfix mindnet_dev, Dev-Qdrant und schreibgeschützter Vault.

Ohne Cloud-Keys (Prod-Standard) ruft der stabile Code für Cloud-Profile Ollama mit der Cloud-Modell-ID auf. Das scheitert zunächst und endet über fallback_profile bei identity_safe (phi3:mini). Chat funktioniert damit lokal, aber mit Verzögerung durch Fehlversuche (Review R4).

8. Altbestand docker/ (MiniLM)

docker/docker-compose.yml und docker/embeddings.Dockerfile bauen einen MiniLM-Dienst (384 Dimensionen, Port 8990). Laut Server-Handbuch läuft mindnet-embed auf llm-node. Im Anwendungscode wird er nicht genutzt; außerdem verweist das Dockerfile auf app/embed_server.py, das im Repository nicht mehr existiert. Nicht entfernen, bevor geprüft ist, ob der Container auf llm-node noch läuft und von irgendetwas angesprochen wird. Grund: deploy.yml synchronisiert docker/ mit rsync --delete; eine Löschung auf main entfernt die Dateien auch auf dem Server.

9. Noch nicht verifiziert

  • Kein docker build und kein Compose-Start: Auf der Entwicklungsmaschine ist kein Docker installiert. Verifiziert sind die Preflight-Logik, statische Compose-/Dockerfile-Zusagen (tests/test_container_preflight.py) und die Testsuite mit exakt den gelockten Versionen (frische venv aus dem Lock, Windows).
  • Healthcheck von qdrant/qdrant nutzt bash und /dev/tcp; beim ersten Dev-Build prüfen.
  • Der Abgleich mit den produktiven Paketversionen fehlt (Abschnitt 2).