Merge feature/containerization into develop
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
commit
7f5cdeb4cb
23 files changed
+3502
No files matched your search
@@ -0,0 +1,20 @@
|
|||||||
|
# Allowlist: Nur was hier ausdrücklich freigegeben ist, gelangt in den Build-Kontext.
|
||||||
|
# Damit landen weder .env-Dateien, Vault-Inhalte, Logs noch lokale venvs im Image.
|
||||||
|
**
|
||||||
|
|
||||||
|
!app/
|
||||||
|
!config/
|
||||||
|
!scripts/
|
||||||
|
!tests/
|
||||||
|
!deploy/
|
||||||
|
|
||||||
|
# Innerhalb der freigegebenen Ordner wieder ausschließen
|
||||||
|
**/__pycache__/
|
||||||
|
**/*.pyc
|
||||||
|
**/.pytest_cache/
|
||||||
|
config/*.env
|
||||||
|
config/*.local.*
|
||||||
|
config/*_old*
|
||||||
|
config/* - Kopie*
|
||||||
|
deploy/env/*.env
|
||||||
|
tests/temp_*/
|
||||||
@@ -0,0 +1,2 @@
|
|||||||
|
# Shell-Skripte laufen im Container bzw. auf dem Linux-Runner.
|
||||||
|
*.sh text eol=lf
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
__pycache__/
|
||||||
@@ -0,0 +1,63 @@
|
|||||||
|
# syntax=docker/dockerfile:1.7
|
||||||
|
#
|
||||||
|
# Mindnet-Image für API und Streamlit-UI (ein Image, Modus per CMD: api | ui | preflight).
|
||||||
|
# Build-Kontext ist das Repository-Root; die Allowlist steht in /.dockerignore.
|
||||||
|
#
|
||||||
|
# docker build -f deploy/Dockerfile -t mindnet:<git-sha> .
|
||||||
|
#
|
||||||
|
# Reproduzierbarkeit: Basis-Image per Digest, Abhängigkeiten per Hash-Lock
|
||||||
|
# (deploy/requirements.lock). Kein torch / sentence-transformers: Embeddings
|
||||||
|
# kommen ausschließlich von Ollama (nomic-embed-text, 768 Dimensionen).
|
||||||
|
|
||||||
|
ARG PYTHON_IMAGE=python:3.12-slim-bookworm@sha256:e697c81897302a4c4333bade000d98038fbb21eb064f8ee1fd42d02ebcd9d337
|
||||||
|
|
||||||
|
# --- Abhängigkeiten in ein isoliertes venv -----------------------------------
|
||||||
|
FROM ${PYTHON_IMAGE} AS deps
|
||||||
|
ENV PIP_NO_CACHE_DIR=1 \
|
||||||
|
PIP_DISABLE_PIP_VERSION_CHECK=1 \
|
||||||
|
PYTHONDONTWRITEBYTECODE=1
|
||||||
|
COPY deploy/requirements.lock /tmp/requirements.lock
|
||||||
|
RUN python -m venv /opt/venv \
|
||||||
|
&& /opt/venv/bin/pip install --require-hashes --no-deps -r /tmp/requirements.lock
|
||||||
|
|
||||||
|
# --- Laufzeit-Image -------------------------------------------------------------
|
||||||
|
FROM ${PYTHON_IMAGE} AS runtime
|
||||||
|
ARG MINDNET_UID=10001
|
||||||
|
ENV PATH=/opt/venv/bin:${PATH} \
|
||||||
|
PYTHONDONTWRITEBYTECODE=1 \
|
||||||
|
PYTHONUNBUFFERED=1 \
|
||||||
|
PYTHONPATH=/app \
|
||||||
|
HOME=/tmp \
|
||||||
|
STREAMLIT_BROWSER_GATHER_USAGE_STATS=false
|
||||||
|
|
||||||
|
RUN groupadd --system --gid ${MINDNET_UID} mindnet \
|
||||||
|
&& useradd --system --uid ${MINDNET_UID} --gid mindnet --no-create-home --shell /usr/sbin/nologin mindnet
|
||||||
|
|
||||||
|
COPY --from=deps /opt/venv /opt/venv
|
||||||
|
|
||||||
|
WORKDIR /app
|
||||||
|
# Code und Konfiguration gehören root und sind für den Laufzeitnutzer nur lesbar.
|
||||||
|
COPY app/ app/
|
||||||
|
COPY config/ config/
|
||||||
|
COPY scripts/ scripts/
|
||||||
|
COPY deploy/entrypoint.py deploy/healthcheck.py /opt/mindnet/
|
||||||
|
|
||||||
|
# Einzige beschreibbare Pfade (als Volumes gemountet): Logs und Laufzeitdaten.
|
||||||
|
RUN install -d -o mindnet -g mindnet -m 0750 /app/logs /app/data /app/data/logs
|
||||||
|
|
||||||
|
USER mindnet:mindnet
|
||||||
|
EXPOSE 8000 8501
|
||||||
|
ENTRYPOINT ["python", "/opt/mindnet/entrypoint.py"]
|
||||||
|
CMD ["api"]
|
||||||
|
|
||||||
|
# --- Test-Image (nur für nichtproduktive Läufe) ---------------------------------
|
||||||
|
FROM runtime AS test
|
||||||
|
USER root
|
||||||
|
COPY deploy/requirements-test.lock /tmp/requirements-test.lock
|
||||||
|
RUN pip install --no-cache-dir --require-hashes --no-deps -r /tmp/requirements-test.lock
|
||||||
|
COPY tests/ tests/
|
||||||
|
COPY deploy/ deploy/
|
||||||
|
USER mindnet:mindnet
|
||||||
|
ENTRYPOINT []
|
||||||
|
CMD ["python", "-m", "pytest", "-q", "-p", "no:cacheprovider", \
|
||||||
|
"tests/test_container_preflight.py", "tests/test_container_connectivity.py"]
|
||||||
@@ -0,0 +1,114 @@
|
|||||||
|
# Mindnet ENTWICKLUNG als Container: isoliert von Produktion.
|
||||||
|
#
|
||||||
|
# docker compose -f deploy/compose.dev.yml --env-file deploy/env/dev.env up -d --wait
|
||||||
|
#
|
||||||
|
# - Eigene Qdrant-Instanz mit eigenem Volume (Prod-Qdrant wird nie angesprochen).
|
||||||
|
# - Vault: nur Testdaten, nur lesend.
|
||||||
|
# - Ollama ist ein gemeinsamer Host-Dienst (Embeddings).
|
||||||
|
# - Andere Ports und anderer Compose-Projektname als Prod.
|
||||||
|
|
||||||
|
name: mindnet-dev
|
||||||
|
|
||||||
|
x-hardening: &hardening
|
||||||
|
image: mindnet:${MINDNET_IMAGE_TAG:-dev}
|
||||||
|
build:
|
||||||
|
context: ..
|
||||||
|
dockerfile: deploy/Dockerfile
|
||||||
|
target: runtime
|
||||||
|
env_file: ["${MINDNET_ENV_FILE:-env/dev.env}"]
|
||||||
|
read_only: true
|
||||||
|
tmpfs: ["/tmp:size=64m,mode=1777"]
|
||||||
|
cap_drop: [ALL]
|
||||||
|
security_opt: ["no-new-privileges:true"]
|
||||||
|
init: true
|
||||||
|
pids_limit: 256
|
||||||
|
restart: unless-stopped
|
||||||
|
extra_hosts: ["host.docker.internal:host-gateway"]
|
||||||
|
logging:
|
||||||
|
driver: json-file
|
||||||
|
options: {max-size: "10m", max-file: "3"}
|
||||||
|
networks: [mindnet-dev]
|
||||||
|
|
||||||
|
x-fixed-env: &fixed-env
|
||||||
|
MINDNET_ENV: dev
|
||||||
|
COLLECTION_PREFIX: mindnet_dev
|
||||||
|
QDRANT_URL: http://qdrant:6333
|
||||||
|
VECTOR_DIM: "768"
|
||||||
|
MINDNET_EXPECTED_VECTOR_DIM: "768"
|
||||||
|
MINDNET_EXPECTED_EMBEDDING_MODEL: nomic-embed-text
|
||||||
|
MINDNET_VAULT_ROOT: /vault
|
||||||
|
MINDNET_VAULT_READONLY: "true"
|
||||||
|
MINDNET_VOCAB_PATH: /vault/_system/dictionary/edge_vocabulary.md
|
||||||
|
MINDNET_SCHEMA_PATH: /vault/_system/dictionary/graph_schema.md
|
||||||
|
|
||||||
|
services:
|
||||||
|
qdrant:
|
||||||
|
image: qdrant/qdrant:v1.16.2@sha256:dab6de32f7b2cc599985a7c764db3e8b062f70508fb85ca074aa856f829bf335
|
||||||
|
restart: unless-stopped
|
||||||
|
environment:
|
||||||
|
QDRANT__TELEMETRY_DISABLED: "true"
|
||||||
|
volumes:
|
||||||
|
- qdrant:/qdrant/storage
|
||||||
|
# Standardmäßig nicht veröffentlicht; zum Debuggen optional lokal am Host.
|
||||||
|
ports: ["127.0.0.1:${MINDNET_DEV_QDRANT_PORT:-6343}:6333"]
|
||||||
|
healthcheck:
|
||||||
|
test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/6333"]
|
||||||
|
interval: 10s
|
||||||
|
timeout: 5s
|
||||||
|
retries: 10
|
||||||
|
networks: [mindnet-dev]
|
||||||
|
|
||||||
|
api:
|
||||||
|
<<: *hardening
|
||||||
|
command: ["api"]
|
||||||
|
environment:
|
||||||
|
<<: *fixed-env
|
||||||
|
volumes:
|
||||||
|
- type: bind
|
||||||
|
source: ${MINDNET_VAULT_HOST_PATH:?MINDNET_VAULT_HOST_PATH auf ein Testdaten-Verzeichnis setzen}
|
||||||
|
target: /vault
|
||||||
|
read_only: true
|
||||||
|
bind:
|
||||||
|
create_host_path: false
|
||||||
|
propagation: rslave
|
||||||
|
- logs:/app/logs
|
||||||
|
- data:/app/data
|
||||||
|
ports: ["127.0.0.1:${MINDNET_API_PORT:-8012}:8000"]
|
||||||
|
mem_limit: ${MINDNET_API_MEM_LIMIT:-2g}
|
||||||
|
depends_on:
|
||||||
|
qdrant: {condition: service_healthy}
|
||||||
|
healthcheck:
|
||||||
|
test: ["CMD", "python", "/opt/mindnet/healthcheck.py", "api"]
|
||||||
|
interval: 30s
|
||||||
|
timeout: 10s
|
||||||
|
retries: 3
|
||||||
|
start_period: 40s
|
||||||
|
|
||||||
|
ui:
|
||||||
|
<<: *hardening
|
||||||
|
command: ["ui"]
|
||||||
|
environment:
|
||||||
|
<<: *fixed-env
|
||||||
|
MINDNET_VAULT_REQUIRED: "false"
|
||||||
|
MINDNET_API_URL: http://api:8000
|
||||||
|
volumes:
|
||||||
|
- data:/app/data:ro
|
||||||
|
ports: ["${MINDNET_UI_BIND:-127.0.0.1}:${MINDNET_UI_PORT:-8512}:8501"]
|
||||||
|
mem_limit: ${MINDNET_UI_MEM_LIMIT:-1g}
|
||||||
|
depends_on:
|
||||||
|
api: {condition: service_healthy}
|
||||||
|
healthcheck:
|
||||||
|
test: ["CMD", "python", "/opt/mindnet/healthcheck.py", "ui"]
|
||||||
|
interval: 30s
|
||||||
|
timeout: 10s
|
||||||
|
retries: 3
|
||||||
|
start_period: 30s
|
||||||
|
|
||||||
|
volumes:
|
||||||
|
qdrant:
|
||||||
|
logs:
|
||||||
|
data:
|
||||||
|
|
||||||
|
networks:
|
||||||
|
mindnet-dev:
|
||||||
|
driver: bridge
|
||||||
@@ -0,0 +1,97 @@
|
|||||||
|
# Mindnet PRODUKTION als Container (Vorbereitung, noch NICHT aktiv).
|
||||||
|
#
|
||||||
|
# docker compose -f deploy/compose.prod.yml --env-file deploy/env/prod.env up -d --wait
|
||||||
|
#
|
||||||
|
# Grenzen dieses Stands (siehe docs/04_Operations/04_docker_deployment.md):
|
||||||
|
# - Nutzt die bestehende produktive Qdrant-Instanz auf dem Host, startet KEINE eigene.
|
||||||
|
# - Vault ist zwingend schreibgeschützt, bis R2 (Pfad-Traversal in /ingest/save) behoben ist.
|
||||||
|
# - Ollama ist ein gemeinsamer Host-Dienst (Embeddings), kein Teil dieses Stacks.
|
||||||
|
# - Ports weichen bewusst von den systemd-Diensten (8001/8501) ab, damit nichts kollidiert.
|
||||||
|
# - Start auf llm-node erfordert eine gesonderte Freigabe.
|
||||||
|
|
||||||
|
name: mindnet-prod
|
||||||
|
|
||||||
|
x-hardening: &hardening
|
||||||
|
image: mindnet:${MINDNET_IMAGE_TAG:?MINDNET_IMAGE_TAG setzen (z. B. Git-SHA)}
|
||||||
|
build:
|
||||||
|
context: ..
|
||||||
|
dockerfile: deploy/Dockerfile
|
||||||
|
target: runtime
|
||||||
|
env_file: ["${MINDNET_ENV_FILE:-env/prod.env}"]
|
||||||
|
read_only: true
|
||||||
|
tmpfs: ["/tmp:size=64m,mode=1777"]
|
||||||
|
cap_drop: [ALL]
|
||||||
|
security_opt: ["no-new-privileges:true"]
|
||||||
|
init: true
|
||||||
|
pids_limit: 256
|
||||||
|
restart: unless-stopped
|
||||||
|
extra_hosts: ["host.docker.internal:host-gateway"]
|
||||||
|
logging:
|
||||||
|
driver: json-file
|
||||||
|
options: {max-size: "10m", max-file: "3"}
|
||||||
|
networks: [mindnet-prod]
|
||||||
|
|
||||||
|
# Werte, die nicht per env-Datei überschrieben werden dürfen.
|
||||||
|
x-fixed-env: &fixed-env
|
||||||
|
MINDNET_ENV: prod
|
||||||
|
VECTOR_DIM: "768"
|
||||||
|
MINDNET_EXPECTED_VECTOR_DIM: "768"
|
||||||
|
MINDNET_EXPECTED_EMBEDDING_MODEL: nomic-embed-text
|
||||||
|
MINDNET_VAULT_ROOT: /vault
|
||||||
|
MINDNET_VAULT_READONLY: "true"
|
||||||
|
MINDNET_VOCAB_PATH: /vault/_system/dictionary/edge_vocabulary.md
|
||||||
|
MINDNET_SCHEMA_PATH: /vault/_system/dictionary/graph_schema.md
|
||||||
|
|
||||||
|
services:
|
||||||
|
api:
|
||||||
|
<<: *hardening
|
||||||
|
command: ["api"]
|
||||||
|
environment:
|
||||||
|
<<: *fixed-env
|
||||||
|
volumes:
|
||||||
|
- type: bind
|
||||||
|
source: ${MINDNET_VAULT_HOST_PATH:?MINDNET_VAULT_HOST_PATH setzen (NAS-Mount auf dem Host)}
|
||||||
|
target: /vault
|
||||||
|
read_only: true
|
||||||
|
bind:
|
||||||
|
create_host_path: false
|
||||||
|
propagation: rslave
|
||||||
|
- logs:/app/logs
|
||||||
|
- data:/app/data
|
||||||
|
# API ohne Authentisierung: nur lokal am Host veröffentlichen.
|
||||||
|
ports: ["127.0.0.1:${MINDNET_API_PORT:-8011}:8000"]
|
||||||
|
mem_limit: ${MINDNET_API_MEM_LIMIT:-2g}
|
||||||
|
healthcheck:
|
||||||
|
test: ["CMD", "python", "/opt/mindnet/healthcheck.py", "api"]
|
||||||
|
interval: 30s
|
||||||
|
timeout: 10s
|
||||||
|
retries: 3
|
||||||
|
start_period: 40s
|
||||||
|
|
||||||
|
ui:
|
||||||
|
<<: *hardening
|
||||||
|
command: ["ui"]
|
||||||
|
environment:
|
||||||
|
<<: *fixed-env
|
||||||
|
MINDNET_VAULT_REQUIRED: "false"
|
||||||
|
MINDNET_API_URL: http://api:8000
|
||||||
|
volumes:
|
||||||
|
- data:/app/data:ro
|
||||||
|
ports: ["${MINDNET_UI_BIND:-127.0.0.1}:${MINDNET_UI_PORT:-8511}:8501"]
|
||||||
|
mem_limit: ${MINDNET_UI_MEM_LIMIT:-1g}
|
||||||
|
depends_on:
|
||||||
|
api: {condition: service_healthy}
|
||||||
|
healthcheck:
|
||||||
|
test: ["CMD", "python", "/opt/mindnet/healthcheck.py", "ui"]
|
||||||
|
interval: 30s
|
||||||
|
timeout: 10s
|
||||||
|
retries: 3
|
||||||
|
start_period: 30s
|
||||||
|
|
||||||
|
volumes:
|
||||||
|
logs:
|
||||||
|
data:
|
||||||
|
|
||||||
|
networks:
|
||||||
|
mindnet-prod:
|
||||||
|
driver: bridge
|
||||||
Executable
+89
@@ -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
|
||||||
@@ -0,0 +1,246 @@
|
|||||||
|
"""
|
||||||
|
FILE: deploy/entrypoint.py
|
||||||
|
DESCRIPTION: Container-Entrypoint für Mindnet (API, UI, Preflight).
|
||||||
|
Prüft vor dem Start alle Annahmen, deren Verletzung still Daten
|
||||||
|
verfälschen oder Inhalte nach außen geben würde, und bricht sonst ab:
|
||||||
|
- Vektor-Dimension und Embedding-Modell (768 / nomic-embed-text)
|
||||||
|
- 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
|
||||||
|
- 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]
|
||||||
|
"""
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import json
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
import urllib.error
|
||||||
|
import urllib.parse
|
||||||
|
import urllib.request
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
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):
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
def _flag(name: str, default: str) -> bool:
|
||||||
|
return os.getenv(name, default).strip().lower() == "true"
|
||||||
|
|
||||||
|
|
||||||
|
def check_environment() -> str:
|
||||||
|
env = os.getenv("MINDNET_ENV", "").strip()
|
||||||
|
if env not in {"dev", "prod"}:
|
||||||
|
raise PreflightError("MINDNET_ENV muss 'dev' oder 'prod' sein.")
|
||||||
|
prefix = os.getenv("COLLECTION_PREFIX", "").strip()
|
||||||
|
if not prefix:
|
||||||
|
# Ohne Präfix fällt die App still auf 'mindnet' (= Produktion) zurück.
|
||||||
|
raise PreflightError("COLLECTION_PREFIX muss explizit gesetzt sein.")
|
||||||
|
if env == "dev" and not prefix.endswith("_dev"):
|
||||||
|
raise PreflightError(f"Dev-Umgebung verlangt ein Präfix mit Suffix '_dev' (ist: '{prefix}').")
|
||||||
|
if env == "prod" and prefix.endswith("_dev"):
|
||||||
|
raise PreflightError(f"Prod-Umgebung mit Dev-Präfix '{prefix}'.")
|
||||||
|
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")
|
||||||
|
|
||||||
|
# qdrant.py fällt ohne VECTOR_DIM auf 384 (MiniLM) zurück.
|
||||||
|
dim = os.getenv("VECTOR_DIM", "").strip()
|
||||||
|
if dim != str(expected_dim):
|
||||||
|
raise PreflightError(f"VECTOR_DIM muss {expected_dim} sein (ist: '{dim or 'nicht gesetzt'}').")
|
||||||
|
|
||||||
|
env_model = os.getenv("MINDNET_EMBEDDING_MODEL", "").strip()
|
||||||
|
if env_model and env_model != expected_model:
|
||||||
|
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.
|
||||||
|
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:
|
||||||
|
raise PreflightError(f"Profil embedding_expert muss dimensions={expected_dim} haben.")
|
||||||
|
|
||||||
|
|
||||||
|
def check_cloud_egress() -> None:
|
||||||
|
configured = [k for k in CLOUD_KEYS if os.getenv(k, "").strip()]
|
||||||
|
if configured and not _flag(CLOUD_EGRESS_ACK, "false"):
|
||||||
|
# Ohne Privacy Gateway würden Vault-Inhalte unmaskiert an Cloud-Provider gehen.
|
||||||
|
raise PreflightError(
|
||||||
|
f"Cloud-Keys gesetzt ({', '.join(configured)}), aber {CLOUD_EGRESS_ACK}=true fehlt. "
|
||||||
|
"Ohne Privacy Gateway gehen Vault-Inhalte unmaskiert an den Provider."
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def _is_read_only_mount(path: Path) -> bool:
|
||||||
|
if not hasattr(os, "statvfs"):
|
||||||
|
return False # nicht prüfbar -> als beschreibbar behandeln (fail closed)
|
||||||
|
return bool(os.statvfs(path).f_flag & os.ST_RDONLY)
|
||||||
|
|
||||||
|
|
||||||
|
def check_vault() -> None:
|
||||||
|
if not _flag("MINDNET_VAULT_REQUIRED", "true"):
|
||||||
|
return
|
||||||
|
root = Path(os.getenv("MINDNET_VAULT_ROOT", ""))
|
||||||
|
if not str(root) or not root.is_dir():
|
||||||
|
raise PreflightError(f"Vault-Verzeichnis fehlt: '{root}'.")
|
||||||
|
# Ein ausgefallenes NAS hinterlässt einen leeren Mountpunkt; der Sentinel unterscheidet das.
|
||||||
|
sentinel = root / os.getenv("MINDNET_VAULT_SENTINEL", "_system/dictionary/edge_vocabulary.md")
|
||||||
|
try:
|
||||||
|
with sentinel.open("rb") as f:
|
||||||
|
f.read(1)
|
||||||
|
except OSError:
|
||||||
|
raise PreflightError(f"Vault-Sentinel nicht lesbar: '{sentinel}' (NAS nicht gemountet?).") from None
|
||||||
|
if _flag("MINDNET_VAULT_READONLY", "true") and not _is_read_only_mount(root):
|
||||||
|
raise PreflightError(f"Vault '{root}' ist nicht schreibgeschützt gemountet (':ro' erforderlich).")
|
||||||
|
|
||||||
|
|
||||||
|
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")
|
||||||
|
|
||||||
|
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:
|
||||||
|
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 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:
|
||||||
|
check_environment()
|
||||||
|
check_embeddings()
|
||||||
|
check_cloud_egress()
|
||||||
|
if mode in {"api", "preflight"}:
|
||||||
|
check_service_urls()
|
||||||
|
check_vault()
|
||||||
|
|
||||||
|
|
||||||
|
COMMANDS = {
|
||||||
|
"api": ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "1"],
|
||||||
|
"ui": ["streamlit", "run", "app/frontend/ui.py", "--server.address", "0.0.0.0",
|
||||||
|
"--server.port", "8501", "--server.headless", "true", "--browser.gatherUsageStats", "false"],
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def main(argv: list[str]) -> int:
|
||||||
|
mode = argv[1] if len(argv) > 1 else "api"
|
||||||
|
if mode not in {*COMMANDS, "preflight"}:
|
||||||
|
print(f"Unbekannter Modus '{mode}'. Erlaubt: api, ui, preflight [--live]", file=sys.stderr)
|
||||||
|
return 2
|
||||||
|
try:
|
||||||
|
run_checks(mode)
|
||||||
|
if mode == "preflight" and "--live" in argv:
|
||||||
|
check_live()
|
||||||
|
except PreflightError as e:
|
||||||
|
print(f"preflight: ABBRUCH: {e}", file=sys.stderr)
|
||||||
|
return 1
|
||||||
|
if mode == "preflight":
|
||||||
|
print("preflight: OK")
|
||||||
|
return 0
|
||||||
|
os.execvp(COMMANDS[mode][0], COMMANDS[mode])
|
||||||
|
return 0 # nicht erreichbar
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
sys.exit(main(sys.argv))
|
||||||
@@ -0,0 +1,2 @@
|
|||||||
|
*.env
|
||||||
|
!*.env.example
|
||||||
Vendored
+39
@@ -0,0 +1,39 @@
|
|||||||
|
# Mindnet DEV (Container) – Vorlage. Kopieren nach deploy/env/dev.env (nie committen).
|
||||||
|
# Qdrant-URL und Collection-Präfix sind in compose.dev.yml fest auf die Dev-Instanz gesetzt.
|
||||||
|
|
||||||
|
# --- Compose / Host ------------------------------------------------------------
|
||||||
|
MINDNET_IMAGE_TAG=dev
|
||||||
|
# Host-Pfad eines Verzeichnisses mit TESTDATEN (kein persönlicher Vault); nur lesend.
|
||||||
|
# Muss _system/dictionary/edge_vocabulary.md enthalten (Sentinel), siehe Doku.
|
||||||
|
MINDNET_VAULT_HOST_PATH=
|
||||||
|
MINDNET_API_PORT=8012
|
||||||
|
MINDNET_UI_PORT=8512
|
||||||
|
MINDNET_UI_BIND=127.0.0.1
|
||||||
|
MINDNET_DEV_QDRANT_PORT=6343
|
||||||
|
|
||||||
|
# --- Lokale Modelle (gemeinsamer Host-Dienst) -------------------------------------
|
||||||
|
MINDNET_OLLAMA_URL=http://host.docker.internal:11434
|
||||||
|
MINDNET_EMBEDDING_MODEL=nomic-embed-text
|
||||||
|
MINDNET_LLM_MODEL=phi3:mini
|
||||||
|
MINDNET_LLM_TIMEOUT=300.0
|
||||||
|
MINDNET_LLM_BACKGROUND_LIMIT=2
|
||||||
|
|
||||||
|
# --- Cloud-LLM -------------------------------------------------------------------
|
||||||
|
# Nur mit synthetischen Testdaten zulässig. Dann Keys setzen und
|
||||||
|
# MINDNET_ALLOW_CLOUD_EGRESS=true. Nie mit echten Vault-Inhalten.
|
||||||
|
MINDNET_LLM_PROVIDER=openrouter
|
||||||
|
OPENROUTER_API_KEY=
|
||||||
|
GOOGLE_API_KEY=
|
||||||
|
MINDNET_ALLOW_CLOUD_EGRESS=false
|
||||||
|
MINDNET_LLM_FALLBACK=true
|
||||||
|
MINDNET_LLM_RATE_LIMIT_WAIT=60.0
|
||||||
|
MINDNET_LLM_RATE_LIMIT_RETRIES=3
|
||||||
|
|
||||||
|
# --- Verarbeitung ----------------------------------------------------------------
|
||||||
|
MINDNET_TYPES_FILE=./config/types.yaml
|
||||||
|
MINDNET_CHANGE_DETECTION_MODE=full
|
||||||
|
MINDNET_LLM_VALIDATION_HEADERS=Unzugeordnete Kanten,Edge Pool,Candidates
|
||||||
|
MINDNET_LLM_VALIDATION_HEADER_LEVEL=3
|
||||||
|
MINDNET_NOTE_SCOPE_ZONE_HEADERS=Smart Edges,Relationen,Global Links,Note-Level Relations,Globale Verbindungen
|
||||||
|
MINDNET_NOTE_SCOPE_HEADER_LEVEL=2
|
||||||
|
DEBUG=true
|
||||||
Vendored
+47
@@ -0,0 +1,47 @@
|
|||||||
|
# Mindnet PROD (Container) – Vorlage. Kopieren nach deploy/env/prod.env (nie committen).
|
||||||
|
# Dient zugleich als --env-file für Compose (Interpolation) und als env_file des Containers.
|
||||||
|
# Fest verdrahtete Sicherheitswerte (MINDNET_ENV, VECTOR_DIM, Vault-Pfade, Read-only)
|
||||||
|
# stehen in compose.prod.yml und lassen sich hier NICHT überschreiben.
|
||||||
|
|
||||||
|
# --- Compose / Host ------------------------------------------------------------
|
||||||
|
MINDNET_IMAGE_TAG=
|
||||||
|
# Host-Pfad des NAS-Vaults (muss vor dem Start gemountet sein; wird nur lesend eingebunden)
|
||||||
|
MINDNET_VAULT_HOST_PATH=
|
||||||
|
MINDNET_API_PORT=8011
|
||||||
|
MINDNET_UI_PORT=8511
|
||||||
|
# UI nur lokal veröffentlichen; für LAN-Zugriff explizit die LAN-IP des Hosts setzen
|
||||||
|
MINDNET_UI_BIND=127.0.0.1
|
||||||
|
|
||||||
|
# --- Daten ---------------------------------------------------------------------
|
||||||
|
# Bestehende produktive Qdrant-Instanz auf dem Host (wird nicht verändert)
|
||||||
|
QDRANT_URL=http://host.docker.internal:6333
|
||||||
|
QDRANT_API_KEY=
|
||||||
|
COLLECTION_PREFIX=mindnet
|
||||||
|
|
||||||
|
# --- Lokale Modelle (gemeinsamer Host-Dienst) -------------------------------------
|
||||||
|
MINDNET_OLLAMA_URL=http://host.docker.internal:11434
|
||||||
|
MINDNET_EMBEDDING_MODEL=nomic-embed-text
|
||||||
|
MINDNET_LLM_MODEL=phi3:mini
|
||||||
|
MINDNET_LLM_TIMEOUT=300.0
|
||||||
|
MINDNET_LLM_BACKGROUND_LIMIT=2
|
||||||
|
|
||||||
|
# --- Cloud-LLM -------------------------------------------------------------------
|
||||||
|
# Ohne Privacy Gateway gehen Vault-Inhalte unmaskiert an den Provider.
|
||||||
|
# Daher in PROD leer lassen. Sind Keys gesetzt, startet der Container nur mit
|
||||||
|
# MINDNET_ALLOW_CLOUD_EGRESS=true – das ist in PROD derzeit NICHT freigegeben.
|
||||||
|
MINDNET_LLM_PROVIDER=openrouter
|
||||||
|
OPENROUTER_API_KEY=
|
||||||
|
GOOGLE_API_KEY=
|
||||||
|
MINDNET_ALLOW_CLOUD_EGRESS=false
|
||||||
|
MINDNET_LLM_FALLBACK=true
|
||||||
|
MINDNET_LLM_RATE_LIMIT_WAIT=60.0
|
||||||
|
MINDNET_LLM_RATE_LIMIT_RETRIES=3
|
||||||
|
|
||||||
|
# --- Verarbeitung (aus config/prod.env übernommen) ---------------------------------
|
||||||
|
MINDNET_TYPES_FILE=./config/types.yaml
|
||||||
|
MINDNET_CHANGE_DETECTION_MODE=full
|
||||||
|
MINDNET_LLM_VALIDATION_HEADERS=Unzugeordnete Kanten,Edge Pool,Candidates
|
||||||
|
MINDNET_LLM_VALIDATION_HEADER_LEVEL=3
|
||||||
|
MINDNET_NOTE_SCOPE_ZONE_HEADERS=Smart Edges,Relationen,Global Links,Note-Level Relations,Globale Verbindungen
|
||||||
|
MINDNET_NOTE_SCOPE_HEADER_LEVEL=2
|
||||||
|
DEBUG=false
|
||||||
@@ -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
|
||||||
@@ -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
|
||||||
@@ -0,0 +1,40 @@
|
|||||||
|
"""
|
||||||
|
FILE: deploy/healthcheck.py
|
||||||
|
DESCRIPTION: Docker-Healthcheck für API und UI.
|
||||||
|
API ist nur gesund, wenn /healthz antwortet UND der Vault-Sentinel
|
||||||
|
lesbar ist. Ein zur Laufzeit ausgefallenes NAS wird so als
|
||||||
|
'unhealthy' sichtbar, statt still auf einem leeren Mountpunkt zu laufen.
|
||||||
|
USAGE: healthcheck.py api | ui
|
||||||
|
"""
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
import urllib.request
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
URLS = {
|
||||||
|
"api": "http://127.0.0.1:8000/healthz",
|
||||||
|
"ui": "http://127.0.0.1:8501/_stcore/health",
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def main(mode: str) -> int:
|
||||||
|
try:
|
||||||
|
with urllib.request.urlopen(URLS[mode], timeout=5) as res:
|
||||||
|
if res.status != 200:
|
||||||
|
return 1
|
||||||
|
except Exception as e:
|
||||||
|
print(f"health: {mode} nicht erreichbar ({type(e).__name__})")
|
||||||
|
return 1
|
||||||
|
if mode == "api" and os.getenv("MINDNET_VAULT_REQUIRED", "true").lower() == "true":
|
||||||
|
root = Path(os.getenv("MINDNET_VAULT_ROOT", ""))
|
||||||
|
sentinel = root / os.getenv("MINDNET_VAULT_SENTINEL", "_system/dictionary/edge_vocabulary.md")
|
||||||
|
if not sentinel.is_file():
|
||||||
|
print(f"health: Vault-Sentinel fehlt ({sentinel})")
|
||||||
|
return 1
|
||||||
|
return 0
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else "api"))
|
||||||
@@ -0,0 +1,2 @@
|
|||||||
|
-c requirements.lock
|
||||||
|
pytest>=8.4.2
|
||||||
@@ -0,0 +1,28 @@
|
|||||||
|
colorama==0.4.6 ; sys_platform == 'win32' \
|
||||||
|
--hash=sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44 \
|
||||||
|
--hash=sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6
|
||||||
|
# via
|
||||||
|
# -c requirements.lock
|
||||||
|
# pytest
|
||||||
|
iniconfig==2.3.0 \
|
||||||
|
--hash=sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730 \
|
||||||
|
--hash=sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12
|
||||||
|
# via pytest
|
||||||
|
packaging==26.0 \
|
||||||
|
--hash=sha256:00243ae351a257117b6a241061796684b084ed1c516a08c48a3f7e147a9d80b4 \
|
||||||
|
--hash=sha256:b36f1fef9334a5588b4166f8bcd26a14e521f2b55e6b9de3aaa80d3ff7a37529
|
||||||
|
# via
|
||||||
|
# -c requirements.lock
|
||||||
|
# pytest
|
||||||
|
pluggy==1.6.0 \
|
||||||
|
--hash=sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3 \
|
||||||
|
--hash=sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746
|
||||||
|
# via pytest
|
||||||
|
pygments==2.19.2 \
|
||||||
|
--hash=sha256:636cb2477cec7f8952536970bc533bc43743542f70392ae026374600add5b887 \
|
||||||
|
--hash=sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b
|
||||||
|
# via pytest
|
||||||
|
pytest==9.0.2 \
|
||||||
|
--hash=sha256:711ffd45bf766d5264d487b917733b453d917afd2b0ad65223959f59089f875b \
|
||||||
|
--hash=sha256:75186651a92bd89611d1d9fc20f0b4345fd827c41ccd5c299a868a05d70edf11
|
||||||
|
# via -r requirements-test.in
|
||||||
@@ -0,0 +1,24 @@
|
|||||||
|
# Laufzeit-Abhängigkeiten für die Container-Images (API + UI).
|
||||||
|
# Abgeleitet aus requirements.txt OHNE torch, sentence-transformers und pytest:
|
||||||
|
# - app/embeddings.py (MiniLM) wird von keinem eingebundenen Router importiert;
|
||||||
|
# Embeddings laufen über Ollama (embedding_expert, nomic-embed-text, 768 Dim.).
|
||||||
|
# - pytest steckt nur im Test-Target (requirements-test.in).
|
||||||
|
# Lock neu erzeugen: siehe docs/04_Operations/04_docker_deployment.md, Abschnitt "Lock".
|
||||||
|
fastapi>=0.116.1
|
||||||
|
uvicorn[standard]>=0.35.0
|
||||||
|
httpx>=0.28.1
|
||||||
|
qdrant-client>=1.15.1
|
||||||
|
pydantic>=2.11.7
|
||||||
|
numpy>=2.3.2
|
||||||
|
python-frontmatter>=1.1.0
|
||||||
|
markdown-it-py>=3.0.0
|
||||||
|
PyYAML>=6.0.2
|
||||||
|
python-slugify>=8.0.4
|
||||||
|
python-dotenv>=1.1.1
|
||||||
|
requests>=2.32.5
|
||||||
|
tqdm>=4.67.1
|
||||||
|
streamlit>=1.39.0
|
||||||
|
streamlit-agraph>=0.0.45
|
||||||
|
st-cytoscape
|
||||||
|
google-genai>=0.3.0
|
||||||
|
openai>=1.50.0
|
||||||
File diff suppressed because it is too large.
Load diff
+113
@@ -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())
|
||||||
@@ -0,0 +1,200 @@
|
|||||||
|
---
|
||||||
|
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: 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`). 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.
|
||||||
|
|
||||||
|
## 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).
|
||||||
@@ -0,0 +1,112 @@
|
|||||||
|
---
|
||||||
|
doc_type: development_plan
|
||||||
|
audience: developer, devops
|
||||||
|
scope: docker_migration, release_gates, test_baseline, privacy_gateway
|
||||||
|
status: draft
|
||||||
|
version: 0.1.0
|
||||||
|
context: "Migrationsplan Mindnet → Container (Dev/Prod) mit Freigabe-Gates, Testbaseline und Anforderungen an das Privacy Gateway."
|
||||||
|
---
|
||||||
|
|
||||||
|
# Migrationsplan: Containerisierung
|
||||||
|
|
||||||
|
Stand: 28.10.2026. Betriebsdetails: [Container-Betrieb](../04_Operations/04_docker_deployment.md). Die Review-Befunde R1–R9 stehen in `05_review_2026-09-25.md` auf dem Branch `codex/privacy-gateway`. Der Link funktioniert erst, wenn beide Stände in `develop` zusammengeführt sind.
|
||||||
|
|
||||||
|
## 1. Rahmenbedingungen (entschieden)
|
||||||
|
|
||||||
|
- Ziel-Host bleibt vorerst `llm-node`; nichts ist auf diesen Host oder auf lokale Python-Umgebungen zugeschnitten.
|
||||||
|
- Ollama und GLiNER sind gemeinsame Dienste pro Host. Dev und Prod haben getrennte Konfiguration, Volumes und Compose-Projekte.
|
||||||
|
- Die produktive Qdrant-Instanz bleibt unverändert; Dev hat eine eigene Instanz.
|
||||||
|
- Embeddings: `nomic-embed-text`, 768 Dimensionen. Ein Rückfall auf MiniLM/384 wird technisch verhindert.
|
||||||
|
- Vault vom NAS, nur lesend. Dev bekommt Testdaten. Prod-Schreibzugriff bleibt gesperrt, bis R2 behoben ist.
|
||||||
|
- Containerisierung und Privacy Gateway sind getrennt. Keine echten Vault-Inhalte an Cloud-Anbieter.
|
||||||
|
|
||||||
|
## 2. Befunde aus Phase 0
|
||||||
|
|
||||||
|
| Befund | Auswirkung |
|
||||||
|
| --- | --- |
|
||||||
|
| **Gitea-Repo `Lars/mindnet` ist öffentlich** (`private: false`, anonymes `git ls-remote` möglich) | Push der Gateway-Arbeit **nicht** durchgeführt. Sicherung nur lokal (Commits + Bundle). |
|
||||||
|
| Push auf `main` löst `.gitea/workflows/deploy.yml` aus: `rsync --delete` von `app scripts schemas docker tests config …` nach `/home/llmadmin/mindnet` plus Neustart | Jeder Merge nach `main` ist ein Produktions-Deploy. Container-Dateien liegen deshalb in `deploy/` (nicht synchronisiert). |
|
||||||
|
| `config/prod.env` ist versioniert; Key-Felder enthalten in allen Ständen nur Platzhalter (Länge 9/12) | Kein Leak. Datei bleibt ungenutzt; das Image schließt `config/*.env` aus. |
|
||||||
|
| MiniLM: `app/embeddings.py` und `embed_router` sind nicht eingebunden. `docker/embeddings.Dockerfile` kopiert das nicht mehr existierende `app/embed_server.py`. `mindnet-embed` läuft laut Handbuch auf llm-node | Nicht entfernt. Abschaltung erst nach Prüfung auf llm-node (Gate G2). |
|
||||||
|
| `qdrant.py` fällt ohne `VECTOR_DIM` auf 384 zurück; `IngestionProcessor` legt Collections beim Start an | Preflight erzwingt `VECTOR_DIM=768`. |
|
||||||
|
| Ohne Cloud-Keys ruft der stabile Code Ollama mit Cloud-Modell-IDs auf (R4) | Chat lokal nur über Fallback-Kette; langsamer, aber ohne Egress. |
|
||||||
|
|
||||||
|
## 3. Branches
|
||||||
|
|
||||||
|
| Branch | Basis | Inhalt | Ort |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| `main` | — | Produktion (systemd, Auto-Deploy) | Gitea |
|
||||||
|
| `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 |
|
||||||
|
|
||||||
|
Reihenfolge: `feature/containerization` → `develop`. Das Gateway folgt erst nach der Docker-Anpassung aus Abschnitt 6 und als eigener Merge. Ein Konflikt mit dem Gateway-Branch ist nicht zu erwarten: `deploy/`, `.dockerignore` und die neuen Docs/Tests sind neu, `.gitignore` nur auf dem Gateway-Branch.
|
||||||
|
|
||||||
|
## 4. Testbaseline (17 bestehende Fehler, kategorisiert)
|
||||||
|
|
||||||
|
Gleiches Ergebnis mit lokaler venv und mit einer frischen venv aus `deploy/requirements.lock`: 12 failed, 5 errors. Keiner davon wurde deaktiviert.
|
||||||
|
|
||||||
|
| Kategorie | Tests | Ursache | Empfehlung |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| **A – echter Produktfehler** | `test_query_text_embed_unit::test_query_with_text` | `app/routers/query.py:28` übergibt `log_search(req, res)`; Signatur ist `(query_id, query_text, results, …)`. Das Suchprotokoll für `/query` schlägt im Hintergrund fehl. | Aufruf korrigieren (eigener Fix). |
|
||||||
|
| **A – echter Produktfehler** | `test_query_unit::test_query_hybrid_with_monkeypatch`, `test_retriever_basic::test_hybrid_retrieve_basic` | `retriever.py:401` loggt `req.query[:100]`; bei reiner Vektor-Abfrage ist `query=None` → `TypeError` → HTTP 500. | Logging `None`-sicher machen (eigener Fix). |
|
||||||
|
| **B – veralteter Test (API umgebaut)** | `test_final_wp15_validation`, `test_smart_chunking_integration`, `test_wp15_final` (Collection-Error) | `from app.core import chunker` – Modul existiert nicht mehr (jetzt `app/core/chunking/`). | Auf neue API portieren oder bewusst archivieren. |
|
||||||
|
| B | `test_WP22_intelligence` (4) | `EdgeRegistry(vault_root=…)` – Parameter entfernt. | Portieren. |
|
||||||
|
| B | `test_dialog_full_flow` (2) | `save_note()` verlangt `background_tasks`. | Portieren. |
|
||||||
|
| **C – fachlich klären** | `test_type_registry::test_defaults_when_missing` | Test erwartet `chunk_profile`, Code liefert `chunking_profile`. | Entscheiden, welcher Schlüssel gilt. |
|
||||||
|
| C | `test_retriever_edges::test_hybrid_retrieve_uses_edge_scores` | Erwartetes Ranking (`note:2` vor `note:1`) tritt nicht ein. | Prüfen, ob Edge-Scoring regressiert oder Erwartung veraltet ist. |
|
||||||
|
| **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 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
|
||||||
|
|
||||||
|
| Gate | Inhalt | Wer |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| **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`; 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; 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)
|
||||||
|
|
||||||
|
`create_from_text` setzt `folder`/`filename` per `os.path.join` zusammen und schreibt ungeprüft. Die Container verhindern das derzeit nur über den schreibgeschützten Mount. Vor jedem beschreibbaren Prod-Vault: aufgelösten Zielpfad gegen den aufgelösten Vault prüfen, absolute Pfade und `..` ablehnen, Symlinks berücksichtigen, Überschreibregeln festlegen, Tests ergänzen. Zusätzlich gehört vor `/ingest/*` eine Zugriffsgrenze (Authentisierung).
|
||||||
|
|
||||||
|
### R3 – Section-Types (Pflichtkorrektur vor Integration von `SectionType`)
|
||||||
|
|
||||||
|
`_propagate_section_type_backwards` gruppiert fest auf H2 und überträgt den ersten Typ auf alle Blöcke. Zwei H3-Abschnitte mit unterschiedlichen Typen erhalten denselben Typ, und der H2-Elterntext wird umtypisiert (Reproduktion im Review). **Gesonderte Korrektur** auf dem `SectionType`-Branch mit verschachteltem Regressionstest. Erst danach Merge nach `develop`. In diesem Arbeitspaket bewusst nicht behoben.
|
||||||
|
|
||||||
|
## 6. Phase 2: Privacy Gateway im Container (Anforderungen)
|
||||||
|
|
||||||
|
Gilt für die spätere Anpassung von `require_local_endpoint` und `LocalDetector`. Grundsatz bleibt fail-closed.
|
||||||
|
|
||||||
|
**Zielverbindungen.** Eine Host-Allowlist mit einmaliger DNS-Auflösung reicht nicht. Zwischen Prüfung und Verbindung kann der Name auf eine andere Adresse zeigen (DNS-Rebinding), und Redirects oder Proxies können das Ziel wechseln. Anforderungen:
|
||||||
|
|
||||||
|
1. Allowlist erlaubter Dienste mit Name, Port und Schema (`ollama:11434`, `gliner:8090`), keine Wildcards.
|
||||||
|
2. Auflösung **pro Verbindung**; alle aufgelösten Adressen müssen in erlaubten Netzen liegen (bevorzugt im Compose-Subnetz statt pauschal RFC1918). Sonst Abbruch.
|
||||||
|
3. **Verbinden auf die geprüfte IP** (Pinning über eigenen httpx-Transport bzw. Resolver), Host-Header bzw. SNI bleibt der Name. Danach die tatsächliche Gegenstelle des Sockets (`getpeername`) gegen die geprüfte IP vergleichen.
|
||||||
|
4. `follow_redirects=False`, `trust_env=False` (keine Proxies), keine URL-Credentials; Antwort-Redirects sind Fehler.
|
||||||
|
5. Netzwerkseitig zusätzlich absichern: Detector und Ollama in einem `internal: true`-Netz ohne Internetzugang. Ausgehender Cloud-Verkehr nur aus dem API-Container und perspektivisch über einen Egress-Proxy mit Provider-Allowlist.
|
||||||
|
6. Tests: Rebinding-Simulation (zweite Auflösung liefert öffentliche IP), Redirect-Antwort, Proxy-Variablen gesetzt, IPv6-mapped-IPv4, Link-Local/Metadaten-IP (`169.254.169.254`).
|
||||||
|
|
||||||
|
**Ausfall der Personenerkennung.** Cloud-Aufrufe werden blockiert (`PrivacyError`, kein Fallback). Das ist im Gateway-Branch bereits so umgesetzt.
|
||||||
|
|
||||||
|
**Wiederholungsmechanismus für die Ingestion (Entwurf).** Bisher bekommt eine Notiz `status: error`, wenn die Kantenvalidierung an einem `PrivacyError` scheitert. Ziel ist eine nachvollziehbare, nicht stille Wiederholung:
|
||||||
|
|
||||||
|
1. **Kein Teil-Commit:** Note, Chunks und explizite Kanten werden geschrieben. Kandidaten-Kanten, deren Validierung nicht möglich war, werden **nicht** verworfen und **nicht** als validiert markiert. Sie bleiben mit `validation_state: pending` und einem Reason-Code (`local_detection_failed`, `local_endpoint_required`, …) erhalten.
|
||||||
|
2. **Persistente Warteschlange** im `data`-Volume (z. B. SQLite `data/ingest_retry.db`), Schlüssel `(note_id, content_hash)`: Versuchszähler, `next_attempt_at` mit exponentiellem Backoff, letzter Reason-Code. Keine Inhalte, nur Referenzen.
|
||||||
|
3. **Idempotenz:** Ändert sich die Notiz, wird der alte Eintrag durch den neuen Hash ersetzt. Wiederholung verarbeitet nur die offenen Kandidaten.
|
||||||
|
4. **Auslösung:** Zunächst **manuell** (CLI-Skript bzw. Admin-Endpoint). Ein automatischer Scheduler erst nach gesonderter Freigabe, weil er gegen Produktivdaten läuft.
|
||||||
|
5. **Sichtbarkeit:** `/admin/stats` und Healthcheck-Details melden Anzahl `pending`/`failed`; nach `max_attempts` Status `failed` mit Reason-Code, nie stilles Verwerfen.
|
||||||
|
6. **Tests:** Detector-Ausfall während der Ingestion → Note vorhanden, Kandidaten `pending`, Queue-Eintrag. Erneuter Lauf mit verfügbarem Detector → validiert, Eintrag entfernt.
|
||||||
|
|
||||||
|
## 7. Nächste Schritte
|
||||||
|
|
||||||
|
1. G0: Repo-Sichtbarkeit klären.
|
||||||
|
2. G1: Review/Merge von `feature/containerization` nach `develop`.
|
||||||
|
3. G2: lesende Prüfungen auf llm-node (Kommandos in [Container-Betrieb §4–5](../04_Operations/04_docker_deployment.md)).
|
||||||
|
4. Fix-Pakete A (query/retriever) und R3 separat; Gateway-Anpassung nach Abschnitt 6.
|
||||||
@@ -0,0 +1,258 @@
|
|||||||
|
"""
|
||||||
|
FILE: tests/test_container_connectivity.py
|
||||||
|
DESCRIPTION: Prüft die Erreichbarkeitsprüfungen der Container-Bereitstellung gegen einen
|
||||||
|
lokalen Fake-Server (Ollama, Qdrant, Mindnet-API, Streamlit-UI):
|
||||||
|
- deploy/entrypoint.py: preflight --live (Dienste, Modelle, Dimensionen)
|
||||||
|
- deploy/smoke.py: Smoke-Test nach dem Start
|
||||||
|
Läuft ohne Docker und ohne echte Dienste (auch mit --network none).
|
||||||
|
"""
|
||||||
|
import importlib.util
|
||||||
|
import json
|
||||||
|
import threading
|
||||||
|
import urllib.error
|
||||||
|
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
import pytest
|
||||||
|
|
||||||
|
DEPLOY = Path(__file__).resolve().parents[1] / "deploy"
|
||||||
|
|
||||||
|
|
||||||
|
def _load(name):
|
||||||
|
spec = importlib.util.spec_from_file_location(f"mindnet_{name}", DEPLOY / f"{name}.py")
|
||||||
|
module = importlib.util.module_from_spec(spec)
|
||||||
|
spec.loader.exec_module(module)
|
||||||
|
return module
|
||||||
|
|
||||||
|
|
||||||
|
ep = _load("entrypoint")
|
||||||
|
smoke = _load("smoke")
|
||||||
|
|
||||||
|
|
||||||
|
class FakeServices(ThreadingHTTPServer):
|
||||||
|
"""Ein Server für alle Dienste; Zustand pro Test über Attribute steuerbar."""
|
||||||
|
|
||||||
|
def __init__(self):
|
||||||
|
super().__init__(("127.0.0.1", 0), _Handler)
|
||||||
|
self.models = ["nomic-embed-text:latest", "phi3:mini"]
|
||||||
|
self.embedding_dim = 768
|
||||||
|
self.collections = {"mindnet_dev_notes": 768, "mindnet_dev_chunks": 768}
|
||||||
|
self.api_key = None
|
||||||
|
self.seen_headers = []
|
||||||
|
self.health = {"status": "ok", "prefix": "mindnet_dev"}
|
||||||
|
self.vector_size = 768
|
||||||
|
self.counts = {"notes": 12, "chunks": 80, "edges": 40}
|
||||||
|
self.ui_body = b"ok"
|
||||||
|
|
||||||
|
@property
|
||||||
|
def url(self):
|
||||||
|
return f"http://127.0.0.1:{self.server_address[1]}"
|
||||||
|
|
||||||
|
|
||||||
|
class _Handler(BaseHTTPRequestHandler):
|
||||||
|
def log_message(self, *args):
|
||||||
|
pass
|
||||||
|
|
||||||
|
def _send(self, status, body):
|
||||||
|
data = body if isinstance(body, bytes) else json.dumps(body).encode()
|
||||||
|
self.send_response(status)
|
||||||
|
self.send_header("Content-Length", str(len(data)))
|
||||||
|
self.end_headers()
|
||||||
|
self.wfile.write(data)
|
||||||
|
|
||||||
|
def do_POST(self):
|
||||||
|
srv = self.server
|
||||||
|
self.rfile.read(int(self.headers.get("Content-Length") or 0))
|
||||||
|
if self.path == "/api/embeddings":
|
||||||
|
return self._send(200, {"embedding": [0.1] * srv.embedding_dim})
|
||||||
|
self._send(404, {})
|
||||||
|
|
||||||
|
def do_GET(self):
|
||||||
|
srv = self.server
|
||||||
|
srv.seen_headers.append(dict(self.headers))
|
||||||
|
if self.path.startswith("/collections") and srv.api_key and self.headers.get("api-key") != srv.api_key:
|
||||||
|
return self._send(401, {})
|
||||||
|
if self.path == "/api/tags":
|
||||||
|
return self._send(200, {"models": [{"name": m} for m in srv.models]})
|
||||||
|
if self.path == "/collections":
|
||||||
|
return self._send(200, {"result": {"collections": []}})
|
||||||
|
if self.path.startswith("/collections/"):
|
||||||
|
name = self.path.rsplit("/", 1)[1]
|
||||||
|
if name not in srv.collections:
|
||||||
|
return self._send(404, {})
|
||||||
|
size = srv.collections[name]
|
||||||
|
return self._send(200, {"result": {"config": {"params": {"vectors": {"size": size}}}}})
|
||||||
|
if self.path == "/healthz":
|
||||||
|
return self._send(200, srv.health)
|
||||||
|
if self.path == "/admin/stats":
|
||||||
|
collections = {k: {"name": f"mindnet_dev_{k}", "count": v} for k, v in srv.counts.items()}
|
||||||
|
return self._send(200, {"collections": collections, "config": {"vector_size": srv.vector_size}})
|
||||||
|
if self.path == "/_stcore/health":
|
||||||
|
return self._send(200, srv.ui_body)
|
||||||
|
self._send(404, {})
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def services():
|
||||||
|
srv = FakeServices()
|
||||||
|
thread = threading.Thread(target=srv.serve_forever, daemon=True)
|
||||||
|
thread.start()
|
||||||
|
yield srv
|
||||||
|
srv.shutdown()
|
||||||
|
srv.server_close()
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def live_env(monkeypatch, services):
|
||||||
|
for key in ("QDRANT_API_KEY", "MINDNET_EXPECTED_VECTOR_DIM", "MINDNET_EXPECTED_EMBEDDING_MODEL"):
|
||||||
|
monkeypatch.delenv(key, raising=False)
|
||||||
|
monkeypatch.chdir(DEPLOY.parent)
|
||||||
|
monkeypatch.setenv("MINDNET_OLLAMA_URL", services.url)
|
||||||
|
monkeypatch.setenv("QDRANT_URL", services.url)
|
||||||
|
monkeypatch.setenv("COLLECTION_PREFIX", "mindnet_dev")
|
||||||
|
monkeypatch.setenv("MINDNET_LLM_MODEL", "phi3:mini")
|
||||||
|
return monkeypatch
|
||||||
|
|
||||||
|
|
||||||
|
def _closed_port_url():
|
||||||
|
srv = ThreadingHTTPServer(("127.0.0.1", 0), BaseHTTPRequestHandler)
|
||||||
|
port = srv.server_address[1]
|
||||||
|
srv.server_close()
|
||||||
|
return f"http://127.0.0.1:{port}"
|
||||||
|
|
||||||
|
|
||||||
|
# --- Dienst-URLs (statisch) -------------------------------------------------------------
|
||||||
|
|
||||||
|
@pytest.mark.parametrize("url", ["", "http://127.0.0.1:11434", "http://localhost:6333", "http://0.0.0.0:6333"])
|
||||||
|
def test_service_urls_reject_missing_or_container_local(monkeypatch, url):
|
||||||
|
monkeypatch.setenv("QDRANT_URL", "http://qdrant:6333")
|
||||||
|
monkeypatch.setenv("MINDNET_OLLAMA_URL", url)
|
||||||
|
with pytest.raises(ep.PreflightError, match="MINDNET_OLLAMA_URL"):
|
||||||
|
ep.check_service_urls()
|
||||||
|
|
||||||
|
|
||||||
|
def test_service_urls_accept_host_gateway_and_compose_service(monkeypatch):
|
||||||
|
monkeypatch.setenv("MINDNET_OLLAMA_URL", "http://host.docker.internal:11434")
|
||||||
|
monkeypatch.setenv("QDRANT_URL", "http://qdrant:6333")
|
||||||
|
ep.check_service_urls()
|
||||||
|
|
||||||
|
|
||||||
|
def test_required_models_come_from_ollama_profiles_and_chat_model(live_env):
|
||||||
|
live_env.setenv("MINDNET_LLM_MODEL", "llama3:8b")
|
||||||
|
assert {"nomic-embed-text", "phi3:mini", "llama3:8b"} <= ep.required_ollama_models()
|
||||||
|
|
||||||
|
|
||||||
|
# --- preflight --live ----------------------------------------------------------------------
|
||||||
|
|
||||||
|
def test_live_passes_when_everything_matches(live_env, capsys):
|
||||||
|
ep.check_live()
|
||||||
|
out = capsys.readouterr().out
|
||||||
|
assert "Ollama erreichbar" in out and "Qdrant erreichbar" in out
|
||||||
|
|
||||||
|
|
||||||
|
def test_live_reports_missing_ollama_model(live_env, services):
|
||||||
|
services.models = ["nomic-embed-text:latest"]
|
||||||
|
with pytest.raises(ep.PreflightError, match="phi3:mini"):
|
||||||
|
ep.check_live()
|
||||||
|
|
||||||
|
|
||||||
|
def test_live_does_not_accept_other_tag_as_latest(live_env, services):
|
||||||
|
services.models = ["nomic-embed-text:v1.5", "phi3:mini"]
|
||||||
|
with pytest.raises(ep.PreflightError, match="nomic-embed-text"):
|
||||||
|
ep.check_live()
|
||||||
|
|
||||||
|
|
||||||
|
def test_live_rejects_wrong_embedding_dimension(live_env, services):
|
||||||
|
services.embedding_dim = 384
|
||||||
|
with pytest.raises(ep.PreflightError, match="384 Dimensionen"):
|
||||||
|
ep.check_live()
|
||||||
|
|
||||||
|
|
||||||
|
def test_live_rejects_wrong_collection_dimension(live_env, services):
|
||||||
|
services.collections["mindnet_dev_chunks"] = 384
|
||||||
|
with pytest.raises(ep.PreflightError, match="mindnet_dev_chunks"):
|
||||||
|
ep.check_live()
|
||||||
|
|
||||||
|
|
||||||
|
def test_live_accepts_missing_collections(live_env, services, capsys):
|
||||||
|
services.collections = {}
|
||||||
|
ep.check_live()
|
||||||
|
assert "existiert noch nicht" in capsys.readouterr().out
|
||||||
|
|
||||||
|
|
||||||
|
def test_live_sends_qdrant_api_key(live_env, services):
|
||||||
|
services.api_key = "secret"
|
||||||
|
with pytest.raises(ep.PreflightError, match="HTTP 401"):
|
||||||
|
ep.check_live()
|
||||||
|
live_env.setenv("QDRANT_API_KEY", "secret")
|
||||||
|
ep.check_live()
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize("var", ["MINDNET_OLLAMA_URL", "QDRANT_URL"])
|
||||||
|
def test_live_unreachable_service_is_a_clear_error(live_env, var):
|
||||||
|
live_env.setenv(var, _closed_port_url())
|
||||||
|
with pytest.raises(ep.PreflightError, match="nicht erreichbar"):
|
||||||
|
ep.check_live()
|
||||||
|
|
||||||
|
|
||||||
|
def test_unreachable_host_gateway_hints_at_loopback_binding(monkeypatch):
|
||||||
|
def refuse(*args, **kwargs):
|
||||||
|
raise urllib.error.URLError(ConnectionRefusedError(111, "Connection refused"))
|
||||||
|
|
||||||
|
monkeypatch.setattr(ep.urllib.request, "urlopen", refuse)
|
||||||
|
with pytest.raises(ep.PreflightError, match="nur an 127.0.0.1"):
|
||||||
|
ep._fetch_json("http://host.docker.internal:11434/api/tags")
|
||||||
|
|
||||||
|
|
||||||
|
def test_preflight_live_exits_1_instead_of_traceback(live_env, monkeypatch, tmp_path):
|
||||||
|
root = tmp_path / "vault"
|
||||||
|
(root / "_system" / "dictionary").mkdir(parents=True)
|
||||||
|
(root / "_system" / "dictionary" / "edge_vocabulary.md").write_text("x", encoding="utf-8")
|
||||||
|
for key, value in {"MINDNET_ENV": "dev", "VECTOR_DIM": "768", "MINDNET_VAULT_ROOT": str(root),
|
||||||
|
"OPENROUTER_API_KEY": "", "GOOGLE_API_KEY": "", "MINDNET_EMBEDDING_MODEL": ""}.items():
|
||||||
|
monkeypatch.setenv(key, value)
|
||||||
|
monkeypatch.setattr(ep, "_is_read_only_mount", lambda path: True)
|
||||||
|
monkeypatch.setattr(ep, "check_service_urls", lambda: None) # Fake-Server läuft auf 127.0.0.1
|
||||||
|
assert ep.main(["entrypoint.py", "preflight", "--live"]) == 0
|
||||||
|
monkeypatch.setenv("QDRANT_URL", _closed_port_url())
|
||||||
|
assert ep.main(["entrypoint.py", "preflight", "--live"]) == 1
|
||||||
|
|
||||||
|
|
||||||
|
# --- smoke.py ---------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
def _smoke(services, **kwargs):
|
||||||
|
return smoke.run(services.url, services.url, "mindnet_dev", attempts=1, **kwargs)
|
||||||
|
|
||||||
|
|
||||||
|
def test_smoke_ok(services, capsys):
|
||||||
|
assert _smoke(services) == 0
|
||||||
|
assert "smoke: OK" in capsys.readouterr().out
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize("change", [
|
||||||
|
lambda s: s.health.update(prefix="mindnet"),
|
||||||
|
lambda s: s.health.update(status="degraded"),
|
||||||
|
lambda s: setattr(s, "vector_size", 384),
|
||||||
|
lambda s: setattr(s, "ui_body", b"starting"),
|
||||||
|
])
|
||||||
|
def test_smoke_fails_on_wrong_state(services, change):
|
||||||
|
change(services)
|
||||||
|
assert _smoke(services) == 1
|
||||||
|
|
||||||
|
|
||||||
|
def test_smoke_unreachable_api():
|
||||||
|
url = _closed_port_url()
|
||||||
|
assert smoke.run(url, url, "mindnet_dev", attempts=1) == 1
|
||||||
|
|
||||||
|
|
||||||
|
def test_smoke_missing_collection_warns_in_dev_and_fails_with_require_data(services, capsys):
|
||||||
|
services.counts["edges"] = -1
|
||||||
|
assert _smoke(services) == 0
|
||||||
|
assert "WARNUNG" in capsys.readouterr().out
|
||||||
|
assert _smoke(services, require_data=True) == 1
|
||||||
|
|
||||||
|
|
||||||
|
def test_smoke_require_data_rejects_empty_notes(services):
|
||||||
|
services.counts["notes"] = 0
|
||||||
|
assert _smoke(services) == 0
|
||||||
|
assert _smoke(services, require_data=True) == 1
|
||||||
@@ -0,0 +1,281 @@
|
|||||||
|
"""
|
||||||
|
FILE: tests/test_container_preflight.py
|
||||||
|
DESCRIPTION: Prüft Container-Preflight (deploy/entrypoint.py) und statisch die
|
||||||
|
Sicherheitszusagen der Compose-/Docker-Dateien. Läuft ohne Docker.
|
||||||
|
"""
|
||||||
|
import importlib.util
|
||||||
|
import re
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
import pytest
|
||||||
|
import yaml
|
||||||
|
|
||||||
|
ROOT = Path(__file__).resolve().parents[1]
|
||||||
|
DEPLOY = ROOT / "deploy"
|
||||||
|
SYSTEMD_PORTS = {8001, 8002, 8501, 8502}
|
||||||
|
|
||||||
|
|
||||||
|
def _load_entrypoint():
|
||||||
|
spec = importlib.util.spec_from_file_location("mindnet_entrypoint", DEPLOY / "entrypoint.py")
|
||||||
|
module = importlib.util.module_from_spec(spec)
|
||||||
|
spec.loader.exec_module(module)
|
||||||
|
return module
|
||||||
|
|
||||||
|
|
||||||
|
ep = _load_entrypoint()
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def env(monkeypatch):
|
||||||
|
for key in ("MINDNET_ENV", "COLLECTION_PREFIX", "VECTOR_DIM", "MINDNET_EMBEDDING_MODEL",
|
||||||
|
"OPENROUTER_API_KEY", "GOOGLE_API_KEY", "MINDNET_ALLOW_CLOUD_EGRESS",
|
||||||
|
"MINDNET_VAULT_ROOT", "MINDNET_VAULT_SENTINEL", "MINDNET_VAULT_READONLY",
|
||||||
|
"MINDNET_VAULT_REQUIRED", "MINDNET_EXPECTED_VECTOR_DIM"):
|
||||||
|
monkeypatch.delenv(key, raising=False)
|
||||||
|
monkeypatch.chdir(ROOT)
|
||||||
|
return monkeypatch
|
||||||
|
|
||||||
|
|
||||||
|
# --- Umgebung und Präfix ---------------------------------------------------------
|
||||||
|
|
||||||
|
@pytest.mark.parametrize("menv, prefix", [("", "mindnet"), ("staging", "mindnet"), ("prod", ""),
|
||||||
|
("dev", "mindnet"), ("prod", "mindnet_dev")])
|
||||||
|
def test_environment_rejects_ambiguous_setups(env, menv, prefix):
|
||||||
|
env.setenv("MINDNET_ENV", menv)
|
||||||
|
env.setenv("COLLECTION_PREFIX", prefix)
|
||||||
|
with pytest.raises(ep.PreflightError):
|
||||||
|
ep.check_environment()
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize("menv, prefix", [("dev", "mindnet_dev"), ("prod", "mindnet")])
|
||||||
|
def test_environment_accepts_explicit_setups(env, menv, prefix):
|
||||||
|
env.setenv("MINDNET_ENV", menv)
|
||||||
|
env.setenv("COLLECTION_PREFIX", prefix)
|
||||||
|
assert ep.check_environment() == menv
|
||||||
|
|
||||||
|
|
||||||
|
# --- Embeddings: keine stille Rückkehr zu 384 Dimensionen -----------------------
|
||||||
|
|
||||||
|
@pytest.mark.parametrize("dim", [None, "384", "3072"])
|
||||||
|
def test_embeddings_reject_wrong_or_missing_dim(env, dim):
|
||||||
|
if dim:
|
||||||
|
env.setenv("VECTOR_DIM", dim)
|
||||||
|
with pytest.raises(ep.PreflightError, match="VECTOR_DIM"):
|
||||||
|
ep.check_embeddings()
|
||||||
|
|
||||||
|
|
||||||
|
def test_embeddings_accept_repository_profile(env):
|
||||||
|
env.setenv("VECTOR_DIM", "768")
|
||||||
|
ep.check_embeddings()
|
||||||
|
|
||||||
|
|
||||||
|
def test_embeddings_reject_minilm_override(env):
|
||||||
|
env.setenv("VECTOR_DIM", "768")
|
||||||
|
env.setenv("MINDNET_EMBEDDING_MODEL", "sentence-transformers/all-MiniLM-L6-v2")
|
||||||
|
with pytest.raises(ep.PreflightError, match="MINDNET_EMBEDDING_MODEL"):
|
||||||
|
ep.check_embeddings()
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize("profile", [
|
||||||
|
{"provider": "ollama", "model": "all-minilm", "dimensions": 384},
|
||||||
|
{"provider": "ollama", "model": "nomic-embed-text", "dimensions": 384},
|
||||||
|
{"provider": "ollama", "model": "nomic-embed-text"},
|
||||||
|
])
|
||||||
|
def test_embeddings_reject_bad_profile(env, tmp_path, profile):
|
||||||
|
env.setenv("VECTOR_DIM", "768")
|
||||||
|
path = tmp_path / "profiles.yaml"
|
||||||
|
path.write_text(yaml.safe_dump({"profiles": {"embedding_expert": profile}}), encoding="utf-8")
|
||||||
|
with pytest.raises(ep.PreflightError, match="embedding_expert"):
|
||||||
|
ep.check_embeddings(str(path))
|
||||||
|
|
||||||
|
|
||||||
|
# --- Cloud-Egress ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def test_cloud_keys_require_explicit_ack(env):
|
||||||
|
env.setenv("OPENROUTER_API_KEY", "sk-test")
|
||||||
|
with pytest.raises(ep.PreflightError, match="MINDNET_ALLOW_CLOUD_EGRESS"):
|
||||||
|
ep.check_cloud_egress()
|
||||||
|
env.setenv("MINDNET_ALLOW_CLOUD_EGRESS", "true")
|
||||||
|
ep.check_cloud_egress()
|
||||||
|
|
||||||
|
|
||||||
|
def test_no_cloud_keys_needs_no_ack(env):
|
||||||
|
ep.check_cloud_egress()
|
||||||
|
|
||||||
|
|
||||||
|
# --- Vault / NAS -----------------------------------------------------------------------
|
||||||
|
|
||||||
|
def _vault(tmp_path, with_sentinel=True):
|
||||||
|
root = tmp_path / "vault"
|
||||||
|
root.mkdir()
|
||||||
|
if with_sentinel:
|
||||||
|
sentinel = root / "_system" / "dictionary" / "edge_vocabulary.md"
|
||||||
|
sentinel.parent.mkdir(parents=True)
|
||||||
|
sentinel.write_text("# vocab", encoding="utf-8")
|
||||||
|
return root
|
||||||
|
|
||||||
|
|
||||||
|
def test_vault_missing_directory(env, tmp_path):
|
||||||
|
env.setenv("MINDNET_VAULT_ROOT", str(tmp_path / "nope"))
|
||||||
|
with pytest.raises(ep.PreflightError, match="fehlt"):
|
||||||
|
ep.check_vault()
|
||||||
|
|
||||||
|
|
||||||
|
def test_vault_empty_mountpoint_is_detected(env, tmp_path):
|
||||||
|
# Ausgefallenes NAS: Mountpunkt existiert, ist aber leer.
|
||||||
|
env.setenv("MINDNET_VAULT_ROOT", str(_vault(tmp_path, with_sentinel=False)))
|
||||||
|
with pytest.raises(ep.PreflightError, match="Sentinel"):
|
||||||
|
ep.check_vault()
|
||||||
|
|
||||||
|
|
||||||
|
def test_vault_must_be_read_only(env, tmp_path):
|
||||||
|
env.setenv("MINDNET_VAULT_ROOT", str(_vault(tmp_path)))
|
||||||
|
env.setattr(ep, "_is_read_only_mount", lambda path: False)
|
||||||
|
with pytest.raises(ep.PreflightError, match="schreibgeschützt"):
|
||||||
|
ep.check_vault()
|
||||||
|
env.setattr(ep, "_is_read_only_mount", lambda path: True)
|
||||||
|
ep.check_vault()
|
||||||
|
|
||||||
|
|
||||||
|
def test_read_only_check_fails_closed_without_statvfs(env, tmp_path):
|
||||||
|
env.delattr(ep.os, "statvfs", raising=False)
|
||||||
|
assert ep._is_read_only_mount(tmp_path) is False
|
||||||
|
|
||||||
|
|
||||||
|
def test_unknown_mode_is_rejected():
|
||||||
|
assert ep.main(["entrypoint.py", "shell"]) == 2
|
||||||
|
|
||||||
|
|
||||||
|
# --- Statische Prüfung der Deployment-Dateien ---------------------------------------
|
||||||
|
|
||||||
|
def _compose(name):
|
||||||
|
return yaml.safe_load((DEPLOY / name).read_text(encoding="utf-8"))
|
||||||
|
|
||||||
|
|
||||||
|
def _host_port(mapping):
|
||||||
|
m = re.search(r":(?:\$\{[A-Z_]+:-)?(\d+)\}?:\d+$", mapping)
|
||||||
|
return int(m.group(1))
|
||||||
|
|
||||||
|
|
||||||
|
COMPOSE = {"dev": _compose("compose.dev.yml"), "prod": _compose("compose.prod.yml")}
|
||||||
|
APP_SERVICES = ("api", "ui")
|
||||||
|
|
||||||
|
|
||||||
|
def test_compose_projects_are_separate():
|
||||||
|
assert COMPOSE["dev"]["name"] == "mindnet-dev"
|
||||||
|
assert COMPOSE["prod"]["name"] == "mindnet-prod"
|
||||||
|
assert set(COMPOSE["dev"]["networks"]).isdisjoint(COMPOSE["prod"]["networks"])
|
||||||
|
|
||||||
|
|
||||||
|
def test_compose_ports_do_not_collide():
|
||||||
|
ports = {e: {_host_port(p) for s in c["services"].values() for p in s.get("ports", [])}
|
||||||
|
for e, c in COMPOSE.items()}
|
||||||
|
assert ports["dev"].isdisjoint(ports["prod"])
|
||||||
|
assert not (ports["dev"] | ports["prod"]) & SYSTEMD_PORTS
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize("envname", ["dev", "prod"])
|
||||||
|
def test_compose_app_services_hardened(envname):
|
||||||
|
for name in APP_SERVICES:
|
||||||
|
svc = COMPOSE[envname]["services"][name]
|
||||||
|
assert svc["read_only"] is True
|
||||||
|
assert svc["cap_drop"] == ["ALL"]
|
||||||
|
assert "no-new-privileges:true" in svc["security_opt"]
|
||||||
|
assert svc["environment"]["VECTOR_DIM"] == "768"
|
||||||
|
assert svc["environment"]["MINDNET_VAULT_READONLY"] == "true"
|
||||||
|
assert svc["healthcheck"]["test"][-1] == name
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize("envname", ["dev", "prod"])
|
||||||
|
def test_compose_vault_is_read_only_bind_without_autocreate(envname):
|
||||||
|
mounts = [v for v in COMPOSE[envname]["services"]["api"]["volumes"]
|
||||||
|
if isinstance(v, dict) and v.get("target") == "/vault"]
|
||||||
|
assert len(mounts) == 1
|
||||||
|
assert mounts[0]["read_only"] is True
|
||||||
|
assert mounts[0]["bind"]["create_host_path"] is False
|
||||||
|
assert all(":/vault" not in v for v in COMPOSE[envname]["services"]["ui"]["volumes"] if isinstance(v, str))
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize("envname", ["dev", "prod"])
|
||||||
|
def test_compose_api_only_on_loopback(envname):
|
||||||
|
assert all(p.startswith("127.0.0.1:") for p in COMPOSE[envname]["services"]["api"]["ports"])
|
||||||
|
|
||||||
|
|
||||||
|
def test_prod_uses_existing_qdrant_and_dev_its_own():
|
||||||
|
assert "qdrant" not in COMPOSE["prod"]["services"]
|
||||||
|
dev_qdrant = COMPOSE["dev"]["services"]["qdrant"]
|
||||||
|
assert "@sha256:" in dev_qdrant["image"]
|
||||||
|
for name in APP_SERVICES:
|
||||||
|
dev_env = COMPOSE["dev"]["services"][name]["environment"]
|
||||||
|
assert dev_env["QDRANT_URL"] == "http://qdrant:6333"
|
||||||
|
assert dev_env["COLLECTION_PREFIX"].endswith("_dev")
|
||||||
|
|
||||||
|
|
||||||
|
def test_dockerfile_pinned_and_non_root():
|
||||||
|
text = (DEPLOY / "Dockerfile").read_text(encoding="utf-8")
|
||||||
|
assert re.search(r"ARG PYTHON_IMAGE=python:3\.12-slim-bookworm@sha256:[0-9a-f]{64}", text)
|
||||||
|
runtime = text.split("AS runtime", 1)[1].split("AS test", 1)[0]
|
||||||
|
assert "USER mindnet:mindnet" in runtime
|
||||||
|
assert "--require-hashes" in text
|
||||||
|
|
||||||
|
|
||||||
|
def test_lock_excludes_torch_and_minilm_and_is_hashed():
|
||||||
|
lock = (DEPLOY / "requirements.lock").read_text(encoding="utf-8")
|
||||||
|
pins = re.findall(r"^([a-z0-9][a-z0-9._-]*)==", lock, re.M)
|
||||||
|
assert pins and not {"torch", "sentence-transformers", "transformers"} & set(pins)
|
||||||
|
entries = re.split(r"\n(?=[a-z0-9])", lock.strip())
|
||||||
|
assert all("--hash=sha256:" in e for e in entries if re.match(r"[a-z0-9]", e))
|
||||||
|
|
||||||
|
|
||||||
|
def test_dockerignore_is_allowlist_without_env_files():
|
||||||
|
lines = [l.strip() for l in (ROOT / ".dockerignore").read_text(encoding="utf-8").splitlines()
|
||||||
|
if l.strip() and not l.startswith("#")]
|
||||||
|
assert lines[0] == "**"
|
||||||
|
assert "config/*.env" in lines and "deploy/env/*.env" in lines
|
||||||
|
assert not any(l.startswith("!") and ("vault" in l or ".env" in l) for l in lines)
|
||||||
|
|
||||||
|
|
||||||
|
def test_prod_env_example_blocks_cloud_egress():
|
||||||
|
values = dict(l.split("=", 1) for l in (DEPLOY / "env" / "prod.env.example").read_text(encoding="utf-8").splitlines()
|
||||||
|
if "=" in l and not l.startswith("#"))
|
||||||
|
assert values["OPENROUTER_API_KEY"] == "" and values["GOOGLE_API_KEY"] == ""
|
||||||
|
assert values["MINDNET_ALLOW_CLOUD_EGRESS"] == "false"
|
||||||
|
|
||||||
|
|
||||||
|
# --- Gitea-Workflows und Deploy-Skript (Muster wie Kansho: develop -> dev, main -> prod) ----
|
||||||
|
|
||||||
|
def _workflow(name):
|
||||||
|
data = yaml.safe_load((DEPLOY / "gitea-workflows" / name).read_text(encoding="utf-8"))
|
||||||
|
return data, data.get("on", data.get(True)) # PyYAML liest den Schlüssel 'on' als True
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize("name, branch, envname", [("deploy-dev.yml", "develop", "dev"),
|
||||||
|
("deploy-prod.yml", "main", "prod")])
|
||||||
|
def test_workflow_maps_branch_to_environment(name, branch, envname):
|
||||||
|
wf, on = _workflow(name)
|
||||||
|
assert on["push"]["branches"] == [branch]
|
||||||
|
job = wf["jobs"]["deploy"]
|
||||||
|
assert job["runs-on"] == "linux_host"
|
||||||
|
assert job["env"]["MINDNET_ENV_FILE"].startswith("/") and job["env"]["MINDNET_ENV_FILE"].endswith(f"{envname}.env")
|
||||||
|
assert any(s.get("run") == f"bash deploy/deploy.sh {envname}" for s in job["steps"])
|
||||||
|
|
||||||
|
|
||||||
|
def test_prod_workflow_shares_concurrency_with_systemd_deploy():
|
||||||
|
wf, _ = _workflow("deploy-prod.yml")
|
||||||
|
systemd = yaml.safe_load((ROOT / ".gitea" / "workflows" / "deploy.yml").read_text(encoding="utf-8"))
|
||||||
|
assert wf["concurrency"]["group"] == systemd["concurrency"]["group"]
|
||||||
|
|
||||||
|
|
||||||
|
def test_deploy_script_checks_before_touching_running_stack():
|
||||||
|
script = (DEPLOY / "deploy.sh").read_text(encoding="utf-8")
|
||||||
|
assert "\r" not in script
|
||||||
|
steps = script.split('step "1/5', 1)[1] # ohne Kopfkommentar und Funktionsdefinitionen
|
||||||
|
order = [steps.index(s) for s in ("--network none", "preflight --live", "up -d --wait --no-build && smoke")]
|
||||||
|
assert order == sorted(order)
|
||||||
|
assert "RUN_DEPS=(--no-deps)" in script and "SMOKE_ARGS=(--require-data)" in script
|
||||||
|
assert "last_good_tag" in script
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize("envname", ["dev", "prod"])
|
||||||
|
def test_compose_reads_env_file_from_host(envname):
|
||||||
|
assert COMPOSE[envname]["x-hardening"]["env_file"] == [f"${{MINDNET_ENV_FILE:-env/{envname}.env}}"]
|
||||||
Reference in new issue
Block a user