--- doc_type: operations_manual audience: devops, deployment_engineer scope: docker, compose, container_security, nas_mount status: draft version: 0.3.0 context: "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](04_deployment_guide.md)). 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: ```bash 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: ```bash cd deploy uv pip compile requirements.in --universal --python-version 3.12 \ --exclude-newer --generate-hashes --no-header -o requirements.lock uv pip compile requirements-test.in --universal --python-version 3.12 \ --exclude-newer --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` | | `_notes`/`_chunks` haben 768 Dimensionen; fehlende Collections sind erlaubt (Hinweis) | `Collection … hat Dimension …` | Netzwerkfehler enden als klarer Abbruch mit Exit-Code 1, nicht als Traceback. ```bash 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/` 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: ```bash mountpoint ; findmnt -o TARGET,SOURCE,FSTYPE,OPTIONS,PROPAGATION sudo -u '#10001' test -r /_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:** ```bash 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: ```bash 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: ```bash 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](04_server_operation_manual.md) 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.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](../05_Development/05_docker_migration_plan.md)). Ohne Netzwerk kann kein Test einen echten Dienst erreichen. 3. Image bauen, Tag `-`. 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](04_server_operation_manual.md) 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).