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>
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-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) |
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, 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
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 buildund 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/qdrantnutztbashund/dev/tcp; beim ersten Dev-Build prüfen. - Der Abgleich mit den produktiven Paketversionen fehlt (Abschnitt 2).