Files
mindnet/docs/04_Operations/04_docker_deployment.md
T
LarsandClaude Opus 5.5 6a2ab522fc
Deploy mindnet DEV (Container) / deploy (push) Failing after 30s
Docs: Gitea-Runner läuft als llmadmin, nicht als root
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-28 21:43:19 +01:00

16 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.3.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.

Grundsatz: 1:1-Migration. Der Container betreibt dieselbe Anwendung mit derselben Konfiguration wie die jeweilige systemd-Instanz, damit beide parallel verglichen werden können. Er liest deren .env unverändert. Konfigurationsänderungen sind nachgelagerte Schritte.

1. Überblick

Dev Prod
Vergleichsinstanz (systemd) 8002/8502, /home/llmadmin/mindnet_dev 8001/8501, /home/llmadmin/mindnet
Anwendungskonfiguration /home/llmadmin/mindnet_dev/.env, unverändert /home/llmadmin/mindnet/.env, unverändert
Container-Angaben /home/llmadmin/docker/mindnet-dev/container.env /home/llmadmin/docker/mindnet/container.env
Compose-Datei / Projekt deploy/compose.dev.yml / mindnet-dev deploy/compose.prod.yml / mindnet-prod
API (Standard nur 127.0.0.1) 8012 8011
UI (Standard 0.0.0.0, wie systemd) 8512 8511
Qdrant, Ollama gemeinsame Host-Dienste, wie systemd gemeinsame Host-Dienste, wie systemd
Präfix, Vault aus der .env der systemd-Instanz aus der .env der systemd-Instanz

Die Ports kollidieren weder untereinander noch mit systemd (8001/8002/8501/8502), damit Container und systemd parallel laufen und verglichen werden können.

Abweichungen vom heutigen Verhalten, bewusst und nur diese:

  • Adressen der Host-Dienste: QDRANT_URL und MINDNET_OLLAMA_URL zeigen auf host.docker.internal. 127.0.0.1 wäre im Container der Container selbst. Ziel sind dieselben Dienste.
  • Vault nur lesend: Zwei Instanzen sollen nicht parallel in denselben Vault schreiben. Außerdem ist R2 offen. Speichern aus der Container-UI schlägt deshalb fehl, lesen und suchen funktionieren.
  • Cloud-Keys: Enthält die .env Cloud-Keys, startet der Container nur, wenn in der Container-Datei MINDNET_ALLOW_CLOUD_EGRESS=true steht. Mit true verhält er sich wie heute; die Entscheidung trifft der Betreiber.
  • Bind-Adresse der API: Standard ist 127.0.0.1; über MINDNET_API_BIND lässt sie sich wie bei systemd auf 0.0.0.0 setzen.

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

Umgebung, Dimension, Schreibschutz und die Adressen der Host-Dienste stehen in den Compose-Dateien unter environment und haben Vorrang vor beiden env-Dateien. Präfix und Vault-Pfad kommen aus der .env der systemd-Instanz. Die Präfix-Regel gilt trotzdem: Dev nur *_dev, Prod nie.

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 "$MINDNET_ENV_FILE" run --rm --no-deps api preflight --live   # Variablen wie in Abschnitt 7

4. Vault auf dem NAS

  • Gleicher Vault wie systemd: deploy/appenv.py liest MINDNET_VAULT_ROOT aus der .env. Ein relativer Pfad wird wie bei systemd gegen das WorkingDirectory (Ordner der .env) aufgelöst und im Container unter /app/<pfad> eingehängt, ein absoluter Pfad 1:1. Dadurch zeigt derselbe Wert im Container auf dasselbe Verzeichnis. Fehlt der Wert, gilt der App-Default ./vault_master.
  • 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. Liegt sie im Vault der systemd-Instanz woanders, wird MINDNET_VAULT_SENTINEL in der Container-Datei gesetzt.
  • 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.

Ollama ist seit dem 28.10.2026 für die Docker-Netze freigegeben: OLLAMA_HOST=0.0.0.0:11434 und ufw allow from 172.16.0.0/12 to any port 11434, das LAN bleibt gesperrt. Die Prod-Qdrant ist über ihren veröffentlichten Port 6333 erreichbar.

Die API hat keine Authentisierung und wird standardmäßig nur an 127.0.0.1 veröffentlicht. Die UI erreicht sie intern über http://api:8000. Die UI ist wie bei systemd im LAN erreichbar (MINDNET_UI_BIND=0.0.0.0).

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:

export MINDNET_APP_ENV_FILE=/home/llmadmin/mindnet_dev/.env                      # systemd-Dev, unverändert
export MINDNET_ENV_FILE=/home/llmadmin/docker/mindnet-dev/container.env           # aus deploy/env/dev.env.example
deploy/deploy.sh dev

Für Einzelschritte von Hand braucht Compose zusätzlich die abgeleiteten Vault-Werte:

eval "$(python3 deploy/appenv.py "$MINDNET_APP_ENV_FILE" "$MINDNET_ENV_FILE")"
export MINDNET_VAULT_HOST_PATH MINDNET_VAULT_TARGET MINDNET_IMAGE_TAG=dev-manual
docker compose -f deploy/compose.dev.yml --env-file "$MINDNET_ENV_FILE" up -d --wait

Einen Import startet der Container-Workflow nicht; die Daten sind dieselben wie bei systemd.

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, läuft als llmadmin, nicht wie im Server-Handbuch angegeben 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

Fehlt die Container-Datei, legt der Workflow sie beim ersten Lauf aus deploy/env/<env>.env.example an. Sie enthält nur Ports, Bind-Adressen und Freigaben. Eine vorhandene Datei wird nie überschrieben. deploy/appenv.py bricht ab, wenn darin Anwendungswerte stehen, damit sie die .env der systemd-Instanz nicht überschreiben kann.

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. Vault und Präfix aus der systemd-.env ableiten (deploy/appenv.py), danach preflight --live in einem Wegwerf-Container.
  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.
    • --require-data: alle Collections lesbar, Notes nicht leer, denn die Daten der systemd-Instanz sind vorhanden.
  6. Erfolg: Der Tag wird in last_good_tag neben der Container-Datei vermerkt. Verwaiste Container früherer Stände entfernt --remove-orphans. Prod bei Fehler: Rückkehr zum letzten erfolgreichen Tag und erneuter Smoke-Test; der Workflow bleibt trotzdem rot.

Beide env-Dateien liegen nur auf dem Host (Tabelle in Abschnitt 1). Compose liest sie direkt über MINDNET_APP_ENV_FILE und 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, MINDNET_APP_ENV_FILE und MINDNET_ENV_FILE anpassen. 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).