Add reachability checks and develop/main container pipeline (inactive)
- preflight --live: Ollama/Qdrant reachable from the container, required Ollama models present, 768 dimensions; clear abort instead of traceback. Static check rejects unset or container-local service URLs. - deploy/smoke.py: non-writing post-start check via published ports. - deploy/deploy.sh: test (no network), build, preflight, up --wait, smoke; prod rolls back to the last good image tag. - Workflow templates deploy-dev.yml (push develop) and deploy-prod.yml (push main) following the Kansho pattern; not under .gitea/workflows. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
7a225ba2b6
commit
8f9f83aa79
14 files changed
+728
-90
No files matched your search
@@ -3,7 +3,7 @@ doc_type: operations_manual
|
||||
audience: devops, deployment_engineer
|
||||
scope: docker, compose, container_security, nas_mount
|
||||
status: draft
|
||||
version: 0.1.0
|
||||
version: 0.2.0
|
||||
context: "Container-Betrieb von Mindnet (Dev/Prod) auf llm-node. Vorbereitung, noch keine produktive Umschaltung."
|
||||
---
|
||||
|
||||
@@ -26,7 +26,7 @@ Stand: 28.10.2026. **Status: vorbereitet, nicht aktiv.** Produktion läuft unver
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
@@ -67,10 +67,21 @@ Der aktuelle Lock wurde mit `--exclude-newer 2026-01-22` erzeugt, also dem Stand
|
||||
| `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** die tatsächliche Ollama-Embedding-Länge und die Vektorgröße der Collections `<prefix>_notes` und `<prefix>_chunks`:
|
||||
`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
|
||||
@@ -108,6 +119,14 @@ Für `api` und `ui`: `read_only`-Rootfs, `tmpfs /tmp`, `cap_drop: ALL`, `no-new-
|
||||
|
||||
## 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
|
||||
@@ -127,12 +146,55 @@ Hinweis: Ein Befehl hinter `run` ersetzt nur `CMD`; `entrypoint.py` lehnt unbeka
|
||||
|
||||
**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)
|
||||
## 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`). Die Workflows liegen als **inaktive Vorlagen** unter `deploy/gitea-workflows/`, weil Gitea nur `.gitea/workflows/` ausführt:
|
||||
|
||||
| Workflow | Trigger | Aktivierung |
|
||||
| --- | --- | --- |
|
||||
| `deploy-dev.yml` | Push `develop`, manuell | Gate G3: `git mv` nach `.gitea/workflows/` |
|
||||
| `deploy-prod.yml` | Push `main`, manuell | Gate G5, im **selben Commit** `git rm .gitea/workflows/deploy.yml` (systemd), sonst deployen beide |
|
||||
|
||||
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.
|
||||
|
||||
## 9. Noch nicht verifiziert
|
||||
## 10. Noch nicht verifiziert
|
||||
|
||||
- Kein `docker build` und 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).
|
||||
- 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).
|
||||
@@ -36,7 +36,7 @@ Stand: 28.10.2026. Betriebsdetails: [Container-Betrieb](../04_Operations/04_dock
|
||||
| Branch | Basis | Inhalt | Ort |
|
||||
| --- | --- | --- | --- |
|
||||
| `main` | — | Produktion (systemd, Auto-Deploy) | Gitea |
|
||||
| `develop` | `origin/main` (`0d61a9e`) | Integrationszweig nach Kansho-Muster; noch ohne Deploy | **nur lokal** |
|
||||
| `develop` | `origin/main` (`0d61a9e`) | Integrationszweig nach Kansho-Muster; Push deployt Dev, sobald `deploy-dev.yml` aktiv ist (G3) | **nur lokal** |
|
||||
| `feature/containerization` | `develop` | Phase 1 | **nur lokal** |
|
||||
| `codex/privacy-gateway` | `origin/main` | Gateway (2 Commits), unverändert | **nur lokal** + Bundle |
|
||||
| `origin/SectionType` | `origin/main` | WP-26; R3 offen | Gitea |
|
||||
@@ -59,7 +59,7 @@ Gleiches Ergebnis mit lokaler venv und mit einer frischen venv aus `deploy/requi
|
||||
| **D – braucht Infrastruktur / falsch gepatcht** | `test_graph_unit::test_graph_neighbors` | Patcht nicht mehr die tatsächlich aufgerufene Funktion → echte Qdrant-Verbindung. | Patch korrigieren; danach Unit-Test ohne Qdrant. |
|
||||
| **E – kein pytest-Test** | `test_interview_intent::test_intent`, `test_wp06_decision::test_decision_engine` | Funktionsparameter `message`/`query` werden als Fixture interpretiert; manuelle Skripte gegen laufende Dienste. | Nach `scripts/` verschieben oder als Integrationstest mit Marker. |
|
||||
|
||||
Für eine CI-Pipeline wie bei Kansho: zuerst A beheben, B/D portieren, C entscheiden, E umziehen. Danach ist die Baseline ehrlich grün. Bis dahin sollte eine künftige Test-Pipeline nur prüfen, dass **keine neuen** Fehler gegenüber dieser Liste entstehen.
|
||||
Für eine CI-Pipeline wie bei Kansho: zuerst A beheben, B/D portieren, C entscheiden, E umziehen. Danach ist die Baseline ehrlich grün. Bis dahin läuft die volle Suite in `deploy/deploy.sh` nur informativ; blockierend sind die Container-Tests. Nächster Schritt dafür: eine explizite Liste dieser 17 Fälle, gegen die neue Fehler den Deploy stoppen.
|
||||
|
||||
## 5. Freigabe-Gates
|
||||
|
||||
@@ -68,9 +68,9 @@ Für eine CI-Pipeline wie bei Kansho: zuerst A beheben, B/D portieren, C entsche
|
||||
| **G0** | Repo `Lars/mindnet` auf privat stellen (oder anderes privates Ziel benennen); danach Push von `codex/privacy-gateway`, `develop`, `feature/containerization` | Lars |
|
||||
| **G1** | Review dieses Stands; Merge `feature/containerization` → `develop` | Lars |
|
||||
| **G2** | **Nur lesende** Prüfungen auf llm-node: Docker-/Compose-Version, Port-Bindung Qdrant/Ollama (`ss -ltnp`), `docker ps` (läuft `mindnet-embed`?), `pip freeze` der Prod-venv, NAS-Mount (`findmnt`), Lesbarkeit für UID 10001 | Freigabe Lars |
|
||||
| **G3** | Dev-Stack auf llm-node bauen und starten (eigene Qdrant, Testdaten-Vault), `preflight --live`; Aktivierung der Workflow-Vorlage `deploy/gitea-workflows/deploy-dev.yml.example` | Freigabe Lars |
|
||||
| **G3** | Dev-Stack auf llm-node bauen und starten (eigene Qdrant, Testdaten-Vault), `preflight --live`; danach Aktivierung von `deploy/gitea-workflows/deploy-dev.yml` (jeder Push auf `develop` deployt Dev) | Freigabe Lars |
|
||||
| **G4** | Prod-Container parallel zu systemd starten (nur lesend auf Prod-Qdrant, Vault `ro`), Vergleich der Antworten | Freigabe Lars |
|
||||
| **G5** | Umschaltung Prod auf Container; systemd 2–3 Wochen als Rückfallebene; `deploy.yml` anpassen | Freigabe Lars; Voraussetzung R2, falls Schreibzugriff nötig |
|
||||
| **G5** | Umschaltung Prod auf Container; systemd 2–3 Wochen als Rückfallebene; im selben Commit `deploy-prod.yml` aktivieren und `.gitea/workflows/deploy.yml` entfernen | Freigabe Lars; Voraussetzung R2, falls Schreibzugriff nötig |
|
||||
|
||||
### R2 – Pfadsicherheit beim Speichern (Pflicht vor beschreibbarem Vault)
|
||||
|
||||
|
||||
Reference in new issue
Block a user