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