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

```bash
cp .env.example .env
```

Trage folgende Werte ein:

```env
# 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)

```bash
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:
   ```sql
   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

```bash
# 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

```bash
# 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:

```env
# 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:

```bash
# 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

```bash
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

```yaml
# 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

```bash
# 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:

```dockerfile
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

```bash
# 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

```bash
# 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

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

## 7. Update / Migration

```bash
# 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

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

### Docker Build

```bash
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)