Files
mindnet/docs/04_Operations/04_docker_deployment.md
T
LarsandClaude Opus 5.5 26fa7732e9 Check out from our own Gitea instead of actions/checkout
The runner host failed to resolve github.com; deploys must not depend on
internet DNS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-28 16:45:19 +01:00

15 KiB
Raw Blame History

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.2.0 Container-Betrieb von Mindnet (Dev/Prod) auf llm-node. Vorbereitung, noch keine produktive Umschaltung.

Container-Betrieb (Docker Compose)

Stand: 28.10.2026. Status: Dev aktiv (Push auf develop), Prod 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 9.

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)
MINDNET_OLLAMA_URL/QDRANT_URL fehlen oder zeigen auf localhost/127.0.0.1 App fiele still auf 127.0.0.1 zurück, im Container also auf sich selbst

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 aus dem Container heraus, also über dasselbe Netz wie die API:

Prüfung Fehlerbild bei Abbruch
Ollama /api/tags erreichbar … nicht erreichbar; bei host.docker.internal mit Hinweis auf eine 127.0.0.1-Bindung
Alle Ollama-Modelle vorhanden: Profile mit provider: ollama (heute nomic-embed-text, phi3:mini) plus MINDNET_LLM_MODEL Ollama fehlen die Modelle: …
Ollama liefert für nomic-embed-text 768 Dimensionen Ollama liefert N Dimensionen
Qdrant /collections erreichbar (mit QDRANT_API_KEY, falls gesetzt) nicht erreichbar bzw. HTTP 401
<prefix>_notes/<prefix>_chunks haben 768 Dimensionen; fehlende Collections sind erlaubt (Hinweis) Collection … hat Dimension …

Netzwerkfehler enden als klarer Abbruch mit Exit-Code 1, nicht als Traceback.

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

Normalerweise über das Deploy-Skript (Abschnitt 8), auch manuell:

MINDNET_ENV_FILE=/home/llmadmin/docker/mindnet-dev/dev.env deploy/deploy.sh dev

Einzelschritte von Hand:

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. Gitea-Pipeline: develop → Dev, main → Prod

Gleiches Muster wie Kansho, aber auf dem eigenen Runner des Zielhosts (heute llm-node, Label linux_host, laut Server-Handbuch als root). Gitea führt nur .gitea/workflows/ aus:

Workflow Trigger Status
.gitea/workflows/deploy-dev.yml Push develop, manuell aktiv (G3)
deploy/gitea-workflows/deploy-prod.yml Push main, manuell Vorlage. Aktivierung bei G5, im selben Commit git rm .gitea/workflows/deploy.yml (systemd), sonst deployen beide

Dev-Testdaten: Der Dev-Workflow spiegelt vor jedem Deploy den synthetischen Test-Vault deploy/testvault/ nach /home/llmadmin/docker/mindnet-dev/testvault (erzeugt mit scripts/make_test_vault.py, dazu synthetisches edge_vocabulary.md/graph_schema.md). Fehlt dev.env, legt er sie beim ersten Lauf aus deploy/env/dev.env.example an, ohne Cloud-Keys und mit dem Test-Vault als MINDNET_VAULT_HOST_PATH. Eine vorhandene dev.env wird nie überschrieben. Die Ordner vault/ und vault_master/ im Repo enthalten persönlich wirkende Inhalte und werden nicht verwendet.

Test-Vault in die Dev-Qdrant importieren (manuell, nach dem ersten grünen Deploy; Embeddings über Ollama):

cd <checkout> && export MINDNET_ENV_FILE=/home/llmadmin/docker/mindnet-dev/dev.env
docker compose -f deploy/compose.dev.yml --env-file "$MINDNET_ENV_FILE" run --rm --entrypoint python api \
  -m scripts.import_markdown --vault /vault --prefix mindnet_dev --apply

Prod nur über einen Merge-Commit develop → main (git merge --no-ff develop), wie bei Kansho.

Beide Workflows rufen nur deploy/deploy.sh dev|prod auf. Jeder Schritt bricht ab, bevor der laufende Stack angefasst wird:

  1. Container-Tests im Test-Image mit --network none (Preflight, Erreichbarkeit gegen Fake-Server, statische Compose-/Workflow-Prüfungen), blockierend.
  2. Volle Testsuite mit --network none, informativ, bis die 17 bekannten Fehler behoben sind (Migrationsplan §4). Ohne Netzwerk kann kein Test einen echten Dienst erreichen.
  3. Image bauen, Tag <env>-<commit>.
  4. preflight --live in einem Wegwerf-Container (Prod mit --no-deps; Dev startet dafür die eigene Qdrant).
  5. up -d --wait (Healthchecks) und danach deploy/smoke.py über die veröffentlichten Ports, also aus Sicht des Hosts:
    • API /healthz: Status ok, erwartetes Präfix.
    • API /admin/stats: Vektorgröße 768; die API erreicht Qdrant (Collection-Counts ≠ −1).
    • UI /_stcore/health.
    • Prod zusätzlich --require-data: alle Collections lesbar, Notes nicht leer.
  6. Erfolg: Der Tag wird in last_good_tag neben der env-Datei vermerkt. Prod bei Fehler: Rückkehr zum letzten erfolgreichen Tag und erneuter Smoke-Test; der Workflow bleibt trotzdem rot.

Die env-Dateien liegen nur auf dem Host (/home/llmadmin/docker/mindnet-dev/dev.env, /home/llmadmin/docker/mindnet/prod.env). Die Compose-Dateien lesen sie über MINDNET_ENV_FILE; Secrets landen nicht im Runner-Workspace.

Unterschiede zu Kansho, bewusst:

Kansho Mindnet
Checkout git clone/reset --hard im Zielordner git fetch genau des Push-Commits vom eigenen Gitea in den Runner-Workspace, mit Job-Token (auch bei privatem Repo). Keine externen Actions, also kein Zugriff auf github.com nötig. Compose-Projektnamen sind fest, daher ist der Ordner egal
Tests eigener test.yml nach dem Dev-Deploy Teil des Deploys, vor dem Start; ohne Netzwerk
Prüfung vor Start keine preflight --live (Dienste, Modelle, Dimensionen, Vault)
Image build --no-cache, kein Tag Hash-Lock, Tag pro Commit, Rollback in Prod
Zustand des Hosts .env im Checkout env-Datei und last_good_tag außerhalb des Checkouts

Umzug auf einen anderen Mini-PC: Runner dort registrieren, in beiden Workflows runs-on und MINDNET_ENV_FILE anpassen, env-Dateien und Vault-Mount einrichten. Hostspezifisch ist sonst nur host.docker.internal (über host-gateway, funktioniert auf jedem Linux-Docker).

9. 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.

10. Noch nicht verifiziert

  • Kein docker build und kein Compose-Start: Auf der Entwicklungsmaschine ist kein Docker installiert. Verifiziert sind:
    • die Preflight-Logik und die Erreichbarkeitsprüfungen gegen einen Fake-Server (tests/test_container_connectivity.py),
    • statische Compose-, Dockerfile- und Workflow-Zusagen (tests/test_container_preflight.py),
    • der Ablauf von deploy.sh mit einer Docker-Attrappe: Erfolg, Abbruch im Preflight vor dem Start, Prod-Startfehler mit Rollback,
    • die Testsuite mit exakt den gelockten Versionen (frische venv aus dem Lock, Windows).
  • Runner auf llm-node: Docker-Compose-Version (benötigt up --wait und Interpolation in env_file), Rechte des Runner-Nutzers auf /home/llmadmin/docker/.
  • Healthcheck von qdrant/qdrant nutzt bash und /dev/tcp; beim ersten Dev-Build prüfen.
  • Der Abgleich mit den produktiven Paketversionen fehlt (Abschnitt 2).