224 lines
4.6 KiB
Markdown
224 lines
4.6 KiB
Markdown
# 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) |