NSCT---Neutral-Search-Crawler-Tool/DEPLOYMENT.md

NSCT — Deployment-Anleitung

1. Voraussetzungen

• Docker (≥ 24.0) und Docker Compose (≥ 2.23)
• Mindestens 2 GB freier RAM
• Zugang zu einem OpenAI-kompatiblen LLM-Endpunkt
• PostgreSQL 16+ (wird mit docker-compose bereitgestellt)

2. Konfiguration

2.1 Environment-Datei

cp .env.example .env

Trage folgende Werte ein:

# LLM (verpflichtend)
NSCT_LLM_BASE_URL=http://your-llm-host:8030/openai/v1
NSCT_LLM_MODEL=Qwen3.6-35B
NSCT_LLM_MAX_CONCURRENCY=3
NSCT_LLM_API_KEY=<dein-api-key>

# Vision (optional)
NSCT_VISION_BASE_URL=http://your-vision-host:8030/openai/visual/v1
NSCT_VISION_MODEL=Qwen2.5-VL-3B

# Audio (optional)
NSCT_AUDIO_BASE_URL=http://your-audio-host:8030/hermes-audio
NSCT_AUDIO_MODEL=default

# PostgreSQL
POSTGRES_USER=nsct
POSTGRES_PASSWORD=<starkes-passwort>
POSTGRES_DB=nsct
NSCT_DB_URL=postgresql+asyncpg://nsct:<passwort>@postgres:5432/nsct

# SearXNG (optional)
NSCT_SEARXNG_BASE_URL=http://searxng:8080

# Debug
NSCT_DEBUG=false

3. PostgreSQL Setup

Option A: Docker Compose (empfohlen)

docker compose up postgres

Die Datenbank wird automatisch erstellt. Die Credentials stehen in .env.

Option B: Externe PostgreSQL

1. Erstelle die Datenbank und den User manuell:

   CREATE DATABASE nsct;
   CREATE USER nsct WITH ENCRYPTED PASSWORD '<passwort>';
   GRANT ALL PRIVILEGES ON DATABASE nsct TO nsct;
   

2. Setze NSCT_DB_URL in .env auf den externen Connection String.

4. Deployment-Schritte

4.1 Build und Start

# Vollständiger Stack (API + PostgreSQL + SearXNG)
docker compose up --build

# Nur API und PostgreSQL (kein SearXNG)
docker compose up --build nsct-api postgres

4.2 Gesundheitsprüfung

# Health check
curl http://localhost:8080/health

# Readiness check
curl http://localhost:8080/ready

# Provider-Status
curl http://localhost:8080/providers

4.3 Frontend auf einem separaten Rechner

Der Backend-Stack und das NSCT-Frontend benötigen kein gemeinsames Docker- Netzwerk und können auf unterschiedlichen Rechnern laufen. Das Frontend stellt Browser-Anfragen an seinen Same-Origin-Pfad /api/*; sein Caddy-Proxy leitet diese an das Backend weiter.

Auf dem Frontend-Rechner wird im Frontend-Repository konfiguriert:

# Host:Port des Backend-Rechners, ohne http:// und ohne /api
NSCT_API_UPSTREAM=backend.example.com:8080

Auf dem Backend-Rechner muss die API von diesem Host erreichbar sein:

# Vom Frontend-Rechner aus prüfen
curl http://backend.example.com:8080/health

Die Firewall darf Port 8080 nur für die IP-Adresse oder das private Netz des Frontend-Rechners erlauben. Eine Freigabe für das gesamte Internet ist nicht empfohlen. Werden die Rechner über ein öffentliches oder nicht vertrauenswürdiges Netz verbunden, verwende TLS, ein VPN oder einen abgesicherten Reverse Proxy zwischen Frontend und Backend. Da der Browser ausschließlich mit der Frontend-Domain kommuniziert, ist keine CORS-Freigabe des Backends für Browser- Clients nötig.

4.3 Logs

docker compose logs -f nsct-api

5. Production-Hinweise

5.1 Sicherheit

• .env niemals committen — .gitignore behandelt das
• Verwende ein Secrets-Management Tool (Hashicorp Vault, AWS Secrets Manager)
• Network-Policies für Docker (nur interner Traffic zwischen Services)
• Non-Root-Docker-Container mit Read-Only-Filesystem
• Dropped Capabilities (cap_drop: [ALL])

5.2 Skalierung

• Derzeit: Single-Instance (kein horizontal scaling)
• PostgreSQL: Connection Pooling über pool_size=10, max_overflow=20
• LLM: Max. NSCT_LLM_MAX_CONCURRENCY parallele Requests (default: 3)
• Concurrency-Semaphore im Provider-Layer

5.3 Datenpersistenz

# docker-compose.yml
volumes:
  postgres_data:       # PostgreSQL Daten
    driver: local
  nsct_data:           # NSCT Runtime-Daten
    driver: local

Für Production: Verwende ein volumen-Plugin mit Backup-Unterstützung.

5.4 Monitoring

# Docker Stats
docker stats nsct-api

# Container Logs (letzten 100 Zeilen)
docker compose logs --tail=100 nsct-api

# DB-Größe
docker exec -it nsct-postgres psql -U nsct -d nsct -c "SELECT pg_database_size('nsct');"

# Prometheus Metrics
curl http://localhost:8080/metrics

5.5 Healthcheck

Das Dockerfile enthält einen HEALTHCHECK:

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1

6. Troubleshooting

Problem: API startet nicht

# Logs prüfen
docker compose logs nsct-api

# Häufige Ursachen:
# 1. .env-Datei nicht vorhanden
# 2. PostgreSQL nicht erreichbar
# 3. LLM-Endpoint nicht erreichbar

Problem: PostgreSQL-Verbindung schlägt fehl

# Teste die Verbindung
docker compose exec postgres pg_isready -U nsct -d nsct

# Container-Logs prüfen
docker compose logs postgres

Problem: LLM-Provider nicht erreichbar

# Network-Ping zum LLM-Host
docker compose run --rm nsct-api curl -v http://your-llm-host:8030/openai/v1/models

7. Update / Migration

# Neueste Version holen
git pull

# Container rebuilden
docker compose up --build -d

# Datenbank-Migrationen (wenn benötigt)
# werden in späteren Stages mit Alembic implementiert

8. CI/CD

Unit Tests

.docker compose run --rm nsct-api python -m pytest tests/ -v

Docker Build

docker compose build nsct-api
docker push your-registry/nsct:latest

9. Production Checklist

• .env nicht in Git
• Strong PostgreSQL Password
• LLM API Key konfiguriert
• Resource Limits gesetzt
• Healthcheck konfiguriert
• Logging zu externem System (ELK, Grafana, etc.)
• Backup-Policy für PostgreSQL Volume
• Network Policies für Docker
• Monitoring Alerts (Prometheus + Alertmanager)