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>
15 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.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-bookwormper Digest; Abhängigkeiten ausdeploy/requirements.lockmit--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): Nurapp/,config/,scripts/,tests/unddeploy/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, mitcreate_host_path: false(kein stilles Anlegen) undpropagation: rslave. Ein später wieder eingehängtes NAS wird dadurch im Container sichtbar, sofern der Host-Mountpunktsharedist. - Sentinel: Standard ist
_system/dictionary/edge_vocabulary.mdrelativ zum Vault, einstellbar überMINDNET_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-stoppedversucht 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/savewürde ohneroden fehlenden Vault-Ordner peros.makedirsneu 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-xoder eine passende Gruppe auf dem NAS-Export. Bei CIFS-Mounts geltenuid/gid/file_modeaus 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:
- Container-Tests im Test-Image mit
--network none(Preflight, Erreichbarkeit gegen Fake-Server, statische Compose-/Workflow-Prüfungen), blockierend. - Volle Testsuite mit
--network none, informativ, bis die 17 bekannten Fehler behoben sind (Migrationsplan §4). Ohne Netzwerk kann kein Test einen echten Dienst erreichen. - Image bauen, Tag
<env>-<commit>. preflight --livein einem Wegwerf-Container (Prod mit--no-deps; Dev startet dafür die eigene Qdrant).up -d --wait(Healthchecks) und danachdeploy/smoke.pyüber die veröffentlichten Ports, also aus Sicht des Hosts:- API
/healthz: Statusok, 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.
- API
- Erfolg: Der Tag wird in
last_good_tagneben 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 buildund 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.shmit 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).
- die Preflight-Logik und die Erreichbarkeitsprüfungen gegen einen Fake-Server (
- Runner auf llm-node: Docker-Compose-Version (benötigt
up --waitund Interpolation inenv_file), Rechte des Runner-Nutzers auf/home/llmadmin/docker/. - Healthcheck von
qdrant/qdrantnutztbashund/dev/tcp; beim ersten Dev-Build prüfen. - Der Abgleich mit den produktiven Paketversionen fehlt (Abschnitt 2).