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:
LarsandClaude Opus 5.5 committed 2026-10-28 16:01:37 +01:00
1 parent 7a225ba2b6
commit 8f9f83aa79
14 files changed
+728 -90

No files matched your search

+2 -1
View File
@@ -59,4 +59,5 @@ COPY tests/ tests/
COPY deploy/ deploy/
USER mindnet:mindnet
ENTRYPOINT []
CMD ["python", "-m", "pytest", "-q", "-p", "no:cacheprovider", "tests/test_container_preflight.py"]
CMD ["python", "-m", "pytest", "-q", "-p", "no:cacheprovider", \
"tests/test_container_preflight.py", "tests/test_container_connectivity.py"]
+1 -1
View File
@@ -15,7 +15,7 @@ x-hardening: &hardening
context: ..
dockerfile: deploy/Dockerfile
target: runtime
env_file: [env/dev.env]
env_file: ["${MINDNET_ENV_FILE:-env/dev.env}"]
read_only: true
tmpfs: ["/tmp:size=64m,mode=1777"]
cap_drop: [ALL]
+1 -1
View File
@@ -17,7 +17,7 @@ x-hardening: &hardening
context: ..
dockerfile: deploy/Dockerfile
target: runtime
env_file: [env/prod.env]
env_file: ["${MINDNET_ENV_FILE:-env/prod.env}"]
read_only: true
tmpfs: ["/tmp:size=64m,mode=1777"]
cap_drop: [ALL]
+89
View File
@@ -0,0 +1,89 @@
#!/usr/bin/env bash
# Baut, prüft und startet einen Mindnet-Container-Stack. Genutzt von den
# Gitea-Workflows (develop -> dev, main -> prod) und für manuelle Deploys.
#
# MINDNET_ENV_FILE=/home/llmadmin/docker/mindnet-dev/dev.env deploy/deploy.sh dev
#
# Ablauf (jeder Schritt bricht ab, bevor der laufende Stack angefasst wird):
# 1. Container-Tests im Test-Image, ohne Netzwerk (blockierend)
# 2. volle Testsuite ohne Netzwerk (informativ, bekannte Fehler siehe Migrationsplan)
# 3. Image bauen, Tag = Umgebung + Commit
# 4. preflight --live: Ollama/Qdrant erreichbar, Modelle, 768 Dimensionen, Vault (nur lesend)
# 5. up --wait (Healthchecks), danach smoke.py über die veröffentlichten Ports
# 6. Prod: bei Fehler Rückkehr zum letzten erfolgreichen Tag
#
# Die env-Datei liegt auf dem Host außerhalb von Git; in ihrem Verzeichnis
# merkt sich das Skript den letzten erfolgreichen Image-Tag (last_good_tag).
set -euo pipefail
cd "$(dirname "$0")/.."
ENV="${1:-}"
case "$ENV" in
dev|prod) ;;
*) echo "Aufruf: deploy/deploy.sh dev|prod" >&2; exit 2 ;;
esac
: "${MINDNET_ENV_FILE:?MINDNET_ENV_FILE auf die env-Datei des Hosts setzen}"
[ -f "$MINDNET_ENV_FILE" ] || { echo "env-Datei fehlt: $MINDNET_ENV_FILE" >&2; exit 1; }
export MINDNET_ENV_FILE
SHA="$(git rev-parse --short=12 HEAD)"
export MINDNET_IMAGE_TAG="$ENV-$SHA"
LAST_GOOD="$(dirname "$MINDNET_ENV_FILE")/last_good_tag"
if [ "$ENV" = dev ]; then
PREFIX=mindnet_dev
RUN_DEPS=() # startet die eigene Dev-Qdrant für den Preflight mit
SMOKE_ARGS=()
else
PREFIX="$(sed -n 's/^COLLECTION_PREFIX=//p' "$MINDNET_ENV_FILE" | tail -n 1)"
RUN_DEPS=(--no-deps) # Prod hat keine eigene Qdrant
SMOKE_ARGS=(--require-data)
fi
dc() { docker compose -f "deploy/compose.$ENV.yml" --env-file "$MINDNET_ENV_FILE" "$@"; }
step() { printf '\n=== %s\n' "$*"; }
show_logs() { dc ps || true; dc logs --tail 150 api ui || true; }
published() { dc port "$1" "$2" | head -n 1 | sed 's/^0\.0\.0\.0:/127.0.0.1:/'; }
smoke() {
python3 deploy/smoke.py --api "http://$(published api 8000)" --ui "http://$(published ui 8501)" \
--prefix "$PREFIX" "${SMOKE_ARGS[@]}"
}
step "1/5 Container-Tests (ohne Netzwerk)"
docker build -f deploy/Dockerfile --target test -t "mindnet:test-$SHA" .
docker run --rm --network none "mindnet:test-$SHA"
step "2/5 Volle Testsuite (informativ, ohne Netzwerk)"
if ! docker run --rm --network none "mindnet:test-$SHA" \
python -m pytest tests -q -p no:cacheprovider --continue-on-collection-errors --basetemp=/tmp/pytest; then
echo "WARNUNG: Testsuite nicht grün. Bekannte Fehler: docs/05_Development/05_docker_migration_plan.md"
fi
docker image rm "mindnet:test-$SHA" >/dev/null || true
step "3/5 Image bauen ($MINDNET_IMAGE_TAG)"
dc build api ui
step "4/5 Preflight mit Erreichbarkeit (nur lesend)"
dc run --rm "${RUN_DEPS[@]}" api preflight --live
step "5/5 Start ($MINDNET_IMAGE_TAG) und Smoke"
if dc up -d --wait --no-build && smoke; then
echo "$MINDNET_IMAGE_TAG" > "$LAST_GOOD"
echo "=== mindnet-$ENV läuft mit $MINDNET_IMAGE_TAG"
exit 0
fi
show_logs
PREV="$(cat "$LAST_GOOD" 2>/dev/null || true)"
if [ "$ENV" = prod ] && [ -n "$PREV" ] && [ "$PREV" != "$MINDNET_IMAGE_TAG" ]; then
step "Rollback auf $PREV"
export MINDNET_IMAGE_TAG="$PREV"
if dc up -d --wait --no-build && smoke; then
echo "Rollback erfolgreich; Deploy von $ENV-$SHA ist trotzdem fehlgeschlagen."
else
show_logs
echo "ROLLBACK FEHLGESCHLAGEN, manueller Eingriff nötig." >&2
fi
fi
exit 1
+87 -20
View File
@@ -7,7 +7,10 @@ DESCRIPTION: Container-Entrypoint für Mindnet (API, UI, Preflight).
- explizite Umgebung und Collection-Präfix (Dev nie auf Prod-Präfix)
- Vault: vorhanden, Sentinel lesbar (NAS gemountet), schreibgeschützt
- kein Cloud-LLM-Key ohne ausdrückliche Freigabe
VERSION: 1.0.0
- Dienst-URLs gesetzt und nicht auf den Container selbst (localhost)
Mit 'preflight --live' zusätzlich (nur lesend): Ollama und Qdrant
erreichbar, benötigte Modelle vorhanden, Dimensionen stimmen.
VERSION: 1.1.0
STATUS: Active
USAGE: entrypoint.py api | ui | preflight [--live]
"""
@@ -17,6 +20,7 @@ import json
import os
import sys
import urllib.error
import urllib.parse
import urllib.request
from pathlib import Path
@@ -24,6 +28,8 @@ import yaml
CLOUD_KEYS = ("OPENROUTER_API_KEY", "GOOGLE_API_KEY")
CLOUD_EGRESS_ACK = "MINDNET_ALLOW_CLOUD_EGRESS"
SERVICE_URLS = ("MINDNET_OLLAMA_URL", "QDRANT_URL")
LOOPBACK_HOSTS = {"localhost", "127.0.0.1", "::1", "0.0.0.0"}
class PreflightError(RuntimeError):
@@ -49,6 +55,16 @@ def check_environment() -> str:
return env
def _load_profiles(profiles_path: str | None = None) -> dict:
# Gleicher Pfad wie in der App (Settings kennt keinen Override dafür).
path = Path(profiles_path or "config/llm_profiles.yaml")
try:
data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
except (OSError, yaml.YAMLError) as e:
raise PreflightError(f"LLM-Profile nicht lesbar: {path} ({type(e).__name__}).") from None
return data.get("profiles") or {}
def check_embeddings(profiles_path: str | None = None) -> None:
expected_dim = int(os.getenv("MINDNET_EXPECTED_VECTOR_DIM", "768"))
expected_model = os.getenv("MINDNET_EXPECTED_EMBEDDING_MODEL", "nomic-embed-text")
@@ -63,13 +79,7 @@ def check_embeddings(profiles_path: str | None = None) -> None:
raise PreflightError(f"MINDNET_EMBEDDING_MODEL='{env_model}' weicht von '{expected_model}' ab.")
# Das Profil hat Vorrang vor der Umgebung; fehlt es, fällt der Client auf das Chat-Modell zurück.
# Gleicher Pfad wie in der App (Settings kennt keinen Override dafür).
path = Path(profiles_path or "config/llm_profiles.yaml")
try:
data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
except (OSError, yaml.YAMLError) as e:
raise PreflightError(f"LLM-Profile nicht lesbar: {path} ({type(e).__name__}).") from None
profile = (data.get("profiles") or {}).get("embedding_expert") or {}
profile = _load_profiles(profiles_path).get("embedding_expert") or {}
if profile.get("provider", "ollama") != "ollama" or profile.get("model") != expected_model:
raise PreflightError(f"Profil embedding_expert muss ollama/{expected_model} sein.")
if int(profile.get("dimensions") or 0) != expected_dim:
@@ -109,36 +119,92 @@ def check_vault() -> None:
raise PreflightError(f"Vault '{root}' ist nicht schreibgeschützt gemountet (':ro' erforderlich).")
def check_live() -> None:
"""Optionale Laufzeitprüfung: tatsächliche Embedding- und Collection-Dimension (nur lesend)."""
def check_service_urls() -> None:
for name in SERVICE_URLS:
url = os.getenv(name, "").strip()
if not url:
# Die App fiele sonst still auf http://127.0.0.1:... zurück, also auf den Container selbst.
raise PreflightError(f"{name} muss explizit gesetzt sein.")
if urllib.parse.urlsplit(url).hostname in LOOPBACK_HOSTS:
raise PreflightError(
f"{name}='{url}' zeigt im Container auf den Container selbst. "
"Host-Dienste über host.docker.internal ansprechen."
)
def _fetch_json(url: str, payload: dict | None = None, headers: dict | None = None, timeout: float = 10):
"""GET (oder POST mit payload). Netzwerkfehler werden zu PreflightError, HTTPError bleibt erhalten."""
req = urllib.request.Request(
url, method="POST" if payload is not None else "GET",
data=json.dumps(payload).encode() if payload is not None else None,
headers={"Content-Type": "application/json", **(headers or {})},
)
try:
with urllib.request.urlopen(req, timeout=timeout) as res:
return json.load(res)
except urllib.error.HTTPError:
raise
except (urllib.error.URLError, OSError) as e:
hint = ""
if urllib.parse.urlsplit(url).hostname == "host.docker.internal":
hint = " Lauscht der Dienst auf dem Host nur an 127.0.0.1?"
raise PreflightError(f"{url} nicht erreichbar ({getattr(e, 'reason', e)}).{hint}") from None
except ValueError:
raise PreflightError(f"{url} liefert kein JSON.") from None
def required_ollama_models(profiles_path: str | None = None) -> set[str]:
models = {p["model"] for p in _load_profiles(profiles_path).values()
if isinstance(p, dict) and p.get("provider") == "ollama" and p.get("model")}
# Lokales Chat-Modell: Endpunkt der Fallback-Kette ohne Cloud-Keys (Review R4).
if os.getenv("MINDNET_LLM_MODEL", "").strip():
models.add(os.environ["MINDNET_LLM_MODEL"].strip())
return models
def _has_model(required: str, available: set[str]) -> bool:
return required in available or (":" not in required and f"{required}:latest" in available)
def check_live(profiles_path: str | None = None) -> None:
"""Laufzeitprüfung (nur lesend): Erreichbarkeit, Modelle, Embedding- und Collection-Dimension."""
expected_dim = int(os.getenv("MINDNET_EXPECTED_VECTOR_DIM", "768"))
ollama = os.getenv("MINDNET_OLLAMA_URL", "").rstrip("/")
model = os.getenv("MINDNET_EXPECTED_EMBEDDING_MODEL", "nomic-embed-text")
req = urllib.request.Request(
f"{ollama}/api/embeddings", method="POST",
data=json.dumps({"model": model, "prompt": "preflight"}).encode(),
headers={"Content-Type": "application/json"},
)
with urllib.request.urlopen(req, timeout=30) as res:
got = len(json.load(res).get("embedding") or [])
tags = _fetch_json(f"{ollama}/api/tags")
available = {m.get("name") for m in tags.get("models") or []}
missing = sorted(m for m in required_ollama_models(profiles_path) if not _has_model(m, available))
if missing:
raise PreflightError(f"Ollama ({ollama}) fehlen die Modelle: {', '.join(missing)}.")
embedding = _fetch_json(f"{ollama}/api/embeddings", {"model": model, "prompt": "preflight"}, timeout=30)
got = len(embedding.get("embedding") or [])
if got != expected_dim:
raise PreflightError(f"Ollama liefert {got} Dimensionen für '{model}', erwartet {expected_dim}.")
print(f"preflight: Ollama erreichbar ({ollama}), Modelle vorhanden, '{model}' = {got} Dimensionen.")
qdrant = os.getenv("QDRANT_URL", "").rstrip("/")
headers = {"api-key": os.environ["QDRANT_API_KEY"]} if os.getenv("QDRANT_API_KEY") else {}
try:
_fetch_json(f"{qdrant}/collections", headers=headers)
except urllib.error.HTTPError as e:
raise PreflightError(f"Qdrant ({qdrant}) antwortet mit HTTP {e.code}.") from None
prefix = os.getenv("COLLECTION_PREFIX", "")
for suffix in ("notes", "chunks"):
name = f"{prefix}_{suffix}"
try:
with urllib.request.urlopen(f"{qdrant}/collections/{name}", timeout=10) as res:
vectors = json.load(res)["result"]["config"]["params"]["vectors"]
info = _fetch_json(f"{qdrant}/collections/{name}", headers=headers)
except urllib.error.HTTPError as e:
if e.code == 404:
print(f"preflight: Collection '{name}' existiert noch nicht.")
continue
raise
raise PreflightError(f"Qdrant-Collection '{name}': HTTP {e.code}.") from None
vectors = info["result"]["config"]["params"]["vectors"]
sizes = [vectors["size"]] if "size" in vectors else [v["size"] for v in vectors.values()]
if any(s != expected_dim for s in sizes):
raise PreflightError(f"Collection '{name}' hat Dimension {sizes}, erwartet {expected_dim}.")
print(f"preflight: Qdrant erreichbar ({qdrant}), Collections '{prefix}_*' passen.")
def run_checks(mode: str) -> None:
@@ -146,6 +212,7 @@ def run_checks(mode: str) -> None:
check_embeddings()
check_cloud_egress()
if mode in {"api", "preflight"}:
check_service_urls()
check_vault()
+31
View File
@@ -0,0 +1,31 @@
# VORLAGE, NICHT AKTIV: liegt absichtlich nicht unter .gitea/workflows/.
# Aktivierung erst mit Freigabe (Gate G3, Dev-Start auf dem Runner-Host):
# git mv deploy/gitea-workflows/deploy-dev.yml .gitea/workflows/deploy-dev.yml
# Danach deployt jeder Push auf develop den Dev-Stack (Muster wie Kansho).
# Ablauf und Abbruchbedingungen: deploy/deploy.sh.
name: Deploy mindnet DEV (Container)
on:
push:
branches: [develop]
workflow_dispatch:
concurrency:
group: deploy-mindnet-dev
cancel-in-progress: false
jobs:
deploy:
# Runner auf dem Zielhost (heute llm-node). Bei einem Umzug auf einen anderen
# Mini-PC nur das Label und den Pfad der env-Datei anpassen.
runs-on: linux_host
env:
# Liegt auf dem Host, außerhalb von Git (Vorlage: deploy/env/dev.env.example).
MINDNET_ENV_FILE: /home/llmadmin/docker/mindnet-dev/dev.env
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Test, Build, Preflight, Start, Smoke
run: bash deploy/deploy.sh dev
@@ -1,57 +0,0 @@
# VORLAGE – NICHT AKTIV. Liegt absichtlich außerhalb von .gitea/workflows/.
# Aktivierung (Kopie nach .gitea/workflows/deploy-dev.yml) erst nach Freigabe,
# da der Runner `linux_host` auf llm-node (= Produktionsserver) läuft.
#
# Muster wie Kansho, aber nur manuell auslösbar (workflow_dispatch), kein Push-Trigger.
# Ein PROD-Workflow für Container existiert bewusst noch nicht; der bestehende
# .gitea/workflows/deploy.yml (systemd, Push auf main) bleibt unverändert.
name: Deploy mindnet DEV (Container)
on:
workflow_dispatch:
concurrency:
group: deploy-mindnet-dev
cancel-in-progress: false
jobs:
deploy:
runs-on: linux_host
env:
TARGET: /home/llmadmin/docker/mindnet-dev
COMPOSE: docker compose -f deploy/compose.dev.yml --env-file deploy/env/dev.env
steps:
- name: Checkout develop
run: |
set -euo pipefail
REPO="http://192.168.2.144:3000/Lars/mindnet.git"
mkdir -p "$TARGET" && cd "$TARGET"
if [ ! -d .git ]; then
git clone -b develop "$REPO" .
else
git fetch origin develop
git checkout develop
git reset --hard origin/develop
fi
test -f deploy/env/dev.env || { echo "deploy/env/dev.env fehlt auf dem Host"; exit 1; }
- name: Build (Tag = Commit)
run: |
set -euo pipefail
cd "$TARGET"
export MINDNET_IMAGE_TAG="dev-$(git rev-parse --short HEAD)"
$COMPOSE build --pull
$COMPOSE run --rm --no-deps api preflight
- name: Start und Health
run: |
set -euo pipefail
cd "$TARGET"
export MINDNET_IMAGE_TAG="dev-$(git rev-parse --short HEAD)"
if ! $COMPOSE up -d --wait; then
$COMPOSE logs api --tail 150 || true
$COMPOSE ps || true
exit 1
fi
curl -sf "http://127.0.0.1:${MINDNET_API_PORT:-8012}/healthz"
+33
View File
@@ -0,0 +1,33 @@
# VORLAGE, NICHT AKTIV: liegt absichtlich nicht unter .gitea/workflows/.
# Aktivierung erst bei der Umschaltung (Gate G5, eigene Freigabe), und zwar im
# selben Commit, der .gitea/workflows/deploy.yml (systemd) entfernt:
# git rm .gitea/workflows/deploy.yml
# git mv deploy/gitea-workflows/deploy-prod.yml .gitea/workflows/deploy-prod.yml
# Sonst deployen bei jedem Push auf main beide Wege.
#
# Prod nur über Merge-Commit develop -> main (git merge --no-ff develop), wie bei Kansho.
# Ablauf, Abbruchbedingungen und Rollback: deploy/deploy.sh.
name: Deploy mindnet PROD (Container)
on:
push:
branches: [main]
workflow_dispatch:
concurrency:
# Gleiche Gruppe wie der systemd-Workflow: nie zwei Prod-Deploys gleichzeitig.
group: deploy-mindnet
cancel-in-progress: false
jobs:
deploy:
runs-on: linux_host
env:
MINDNET_ENV_FILE: /home/llmadmin/docker/mindnet/prod.env
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Test, Build, Preflight, Start, Smoke (Rollback bei Fehler)
run: bash deploy/deploy.sh prod
+113
View File
@@ -0,0 +1,113 @@
"""
FILE: deploy/smoke.py
DESCRIPTION: Nicht-schreibender Smoke-Test gegen einen laufenden Mindnet-Stack,
aus Sicht des Hosts über die veröffentlichten Ports. Nur Standardbibliothek,
läuft daher direkt auf dem Runner (python3), ohne venv.
- API /healthz: Status ok, erwartetes Collection-Präfix
- API /admin/stats: Vektorgröße 768; API erreicht Qdrant (Collection-Counts)
- UI /_stcore/health
--require-data (Prod): alle Collections vorhanden und Notes nicht leer.
VERSION: 1.0.0
STATUS: Active
USAGE: smoke.py --api http://127.0.0.1:8012 --ui http://127.0.0.1:8512 --prefix mindnet_dev [--require-data]
"""
from __future__ import annotations
import argparse
import json
import sys
import time
import urllib.error
import urllib.request
EXPECTED_VECTOR_SIZE = 768
class SmokeError(RuntimeError):
pass
def _get(url: str, timeout: float = 15) -> bytes:
try:
with urllib.request.urlopen(url, timeout=timeout) as res:
return res.read()
except urllib.error.HTTPError as e:
raise SmokeError(f"{url}: HTTP {e.code}") from None
except (urllib.error.URLError, OSError) as e:
raise SmokeError(f"{url} nicht erreichbar ({getattr(e, 'reason', e)})") from None
def _get_json(url: str) -> dict:
try:
return json.loads(_get(url))
except ValueError:
raise SmokeError(f"{url} liefert kein JSON") from None
def check_api(api: str, prefix: str, require_data: bool) -> list[str]:
"""Gibt Warnungen zurück; harte Fehler als SmokeError."""
health = _get_json(f"{api}/healthz")
if health.get("status") != "ok":
raise SmokeError(f"/healthz meldet {health.get('status')!r}")
if health.get("prefix") != prefix:
raise SmokeError(f"API nutzt Präfix {health.get('prefix')!r}, erwartet {prefix!r}")
stats = _get_json(f"{api}/admin/stats")
size = (stats.get("config") or {}).get("vector_size")
if size != EXPECTED_VECTOR_SIZE:
raise SmokeError(f"API-Vektorgröße {size}, erwartet {EXPECTED_VECTOR_SIZE}")
warnings = []
collections = stats.get("collections") or {}
for kind in ("notes", "chunks", "edges"):
entry = collections.get(kind) or {}
count = entry.get("count", -1)
if count < 0:
# -1: Collection fehlt oder Qdrant ist aus dem API-Container nicht erreichbar.
msg = f"Collection {entry.get('name', kind)!r} nicht lesbar (fehlt oder Qdrant nicht erreichbar)"
if require_data:
raise SmokeError(msg)
warnings.append(msg)
if require_data and (collections.get("notes") or {}).get("count", 0) <= 0:
raise SmokeError("Notes-Collection ist leer")
return warnings
def check_ui(ui: str) -> None:
body = _get(f"{ui}/_stcore/health").decode("utf-8", "replace").strip()
if body != "ok":
raise SmokeError(f"UI-Health meldet {body!r}")
def run(api: str, ui: str, prefix: str, require_data: bool = False, attempts: int = 1, delay: float = 5) -> int:
api, ui = api.rstrip("/"), ui.rstrip("/")
for attempt in range(1, attempts + 1):
try:
warnings = check_api(api, prefix, require_data)
check_ui(ui)
except SmokeError as e:
if attempt == attempts:
print(f"smoke: FEHLER: {e}", file=sys.stderr)
return 1
time.sleep(delay)
continue
for w in warnings:
print(f"smoke: WARNUNG: {w}")
print(f"smoke: OK (api={api}, ui={ui}, prefix={prefix})")
return 0
return 1
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description=__doc__.split("USAGE:")[0])
parser.add_argument("--api", required=True)
parser.add_argument("--ui", required=True)
parser.add_argument("--prefix", required=True)
parser.add_argument("--require-data", action="store_true")
parser.add_argument("--attempts", type=int, default=3)
args = parser.parse_args(argv)
return run(args.api, args.ui, args.prefix, args.require_data, args.attempts)
if __name__ == "__main__":
sys.exit(main())