Files
mindnet/docs/04_Operations/04_docker_deployment.md
T
LarsandClaude Opus 5.5 9d5b52a3c1 Activate dev container deploy on push to develop
- .gitea/workflows/deploy-dev.yml: prepares the host (synthetic test vault,
  dev.env from the example on first run, never overwritten), then runs
  deploy/deploy.sh dev. Prod workflow stays an inactive template.
- deploy/testvault: synthetic notes from scripts/make_test_vault.py plus
  synthetic edge_vocabulary.md/graph_schema.md (vault sentinel).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-28 16:37:23 +01:00

211 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
doc_type: operations_manual
audience: devops, deployment_engineer
scope: docker, compose, container_security, nas_mount
status: draft
version: 0.2.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.
## 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:
```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 <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.
```bash
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`, 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`. 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-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 <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:**
```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.
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:
```bash
MINDNET_ENV_FILE=/home/llmadmin/docker/mindnet-dev/dev.env deploy/deploy.sh dev
```
Einzelschritte von Hand:
```bash
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.
```bash
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](04_server_operation_manual.md) 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):
```bash
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:
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 `<env>-<commit>`.
4. `preflight --live` in einem Wegwerf-Container (Prod mit `--no-deps`; Dev startet dafür die eigene Qdrant).
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`.
- Prod zusätzlich `--require-data`: alle Collections lesbar, Notes nicht leer.
6. Erfolg: Der Tag wird in `last_good_tag` neben 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 | `actions/checkout` im Runner-Workspace (funktioniert auch bei privatem Repo mit dem Job-Token; 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](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`), Node für `actions/checkout` (nutzt `deploy.yml` heute schon), 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).