Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
16 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.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_URLundMINDNET_OLLAMA_URLzeigen aufhost.docker.internal.127.0.0.1wä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
.envCloud-Keys, startet der Container nur, wenn in der Container-DateiMINDNET_ALLOW_CLOUD_EGRESS=truesteht. Mittrueverhält er sich wie heute; die Entscheidung trifft der Betreiber. - Bind-Adresse der API: Standard ist
127.0.0.1; überMINDNET_API_BINDlässt sie sich wie bei systemd auf0.0.0.0setzen.
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 |
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.pyliestMINDNET_VAULT_ROOTaus der.env. Ein relativer Pfad wird wie bei systemd gegen dasWorkingDirectory(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, 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. Liegt sie im Vault der systemd-Instanz woanders, wirdMINDNET_VAULT_SENTINELin der Container-Datei gesetzt. - 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.
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:
- 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>. - Vault und Präfix aus der systemd-
.envableiten (deploy/appenv.py), danachpreflight --livein einem Wegwerf-Container. 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. --require-data: alle Collections lesbar, Notes nicht leer, denn die Daten der systemd-Instanz sind vorhanden.
- API
- Erfolg: Der Tag wird in
last_good_tagneben 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 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).