Skrift-Kofnigurator/Docker Backend/DEPLOYMENT.md

# Deployment Anleitung - Skrift Backend

## Übersicht

Diese Anleitung zeigt, wie du das Skrift Backend auf deinen vServer deployst.

## Voraussetzungen auf dem Server

- Ubuntu/Debian Linux Server
- Docker und Docker Compose installiert
- Nginx Proxy Manager läuft bereits
- SSH-Zugang zum Server

## Option 1: Docker Image über Docker Hub (EMPFOHLEN)

### Schritt 1: Docker Image erstellen und pushen

Auf deinem lokalen Rechner:

```bash
# 1. Ins Backend-Verzeichnis wechseln
cd "E:\Dokumente\05_Skrift\Frontend_Backend_Konfigurator\Docker Backend"

# 2. Docker Login (benötigt Docker Hub Account)
docker login

# 3. Image bauen (ersetze 'deinusername' mit deinem Docker Hub Username)
docker build -t deinusername/skrift-backend:latest .

# 4. Image zu Docker Hub pushen
docker push deinusername/skrift-backend:latest
```

### Schritt 2: Auf dem Server deployen

Per SSH auf dem Server:

```bash
# 1. Verzeichnis erstellen
mkdir -p /opt/skrift-backend
cd /opt/skrift-backend

# 2. docker-compose.yml erstellen (siehe unten)
nano docker-compose.yml

# 3. .env Datei erstellen
nano .env

# 4. Fonts-Ordner erstellen und Fonts hochladen
mkdir fonts
# Fonts per SCP hochladen (siehe Schritt 3)

# 5. Output-Verzeichnis erstellen
mkdir -p /var/skrift-output
chmod 755 /var/skrift-output

# 6. Container starten
docker-compose up -d

# 7. Logs prüfen
docker-compose logs -f
```

### Schritt 3: Fonts per SCP hochladen

Auf deinem lokalen Rechner:

```bash
# Fonts zum Server kopieren
scp "E:\Dokumente\05_Skrift\Frontend_Backend_Konfigurator\Docker Backend\fonts\*.svg" \
    root@dein-server.de:/opt/skrift-backend/fonts/
```

### docker-compose.yml für Server

```yaml
version: '3.8'

services:
  skrift-backend:
    image: deinusername/skrift-backend:latest  # Dein Docker Hub Image
    container_name: skrift-backend
    restart: unless-stopped
    ports:
      - "4000:4000"  # Oder anderer Port
    environment:
      - NODE_ENV=production
      - PORT=4000
      - SCRIPTALIZER_LICENSE_KEY=${SCRIPTALIZER_LICENSE_KEY}
      - SCRIPTALIZER_ERR_FREQUENCY=0
      - BATCH_SIZE=30
      - CACHE_LIFETIME_HOURS=2
      - RATE_LIMIT_PER_MINUTE=2
    volumes:
      - ./fonts:/app/fonts:ro
      - skrift-cache:/app/cache
      - /var/skrift-output:/app/output
    networks:
      - skrift-network

volumes:
  skrift-cache:
    driver: local

networks:
  skrift-network:
    driver: bridge
```

### .env Datei für Server

```bash
# Scriptalizer API
SCRIPTALIZER_LICENSE_KEY=f9918b40-d11c-11f0-b558-0800200c9a66
SCRIPTALIZER_ERR_FREQUENCY=0

# Preview Settings
BATCH_SIZE=30
CACHE_LIFETIME_HOURS=2
RATE_LIMIT_PER_MINUTE=2

# Environment
NODE_ENV=production
```

## Option 2: Direkt vom Server bauen

### Schritt 1: Code auf Server übertragen

```bash
# Auf lokalem Rechner: Komplettes Backend-Verzeichnis kopieren
scp -r "E:\Dokumente\05_Skrift\Frontend_Backend_Konfigurator\Docker Backend" \
    root@dein-server.de:/opt/skrift-backend/

# Oder mit rsync (besser):
rsync -avz --exclude 'node_modules' --exclude 'output' --exclude 'cache' \
    "E:\Dokumente\05_Skrift\Frontend_Backend_Konfigurator\Docker Backend/" \
    root@dein-server.de:/opt/skrift-backend/
```

### Schritt 2: Auf Server bauen und starten

```bash
# Per SSH auf dem Server
cd /opt/skrift-backend

# Output-Verzeichnis erstellen
mkdir -p /var/skrift-output
chmod 755 /var/skrift-output

# Container bauen und starten
docker-compose up -d --build

# Logs prüfen
docker-compose logs -f
```

## Option 3: Mit GitHub/GitLab (BESTE PRAXIS für Produktion)

### Schritt 1: Repository erstellen

```bash
# Auf lokalem Rechner
cd "E:\Dokumente\05_Skrift\Frontend_Backend_Konfigurator\Docker Backend"

git init
git add .
git commit -m "Initial commit"

# GitHub/GitLab Repository erstellen, dann:
git remote add origin https://github.com/deinusername/skrift-backend.git
git push -u origin main
```

### Schritt 2: Auf Server clonen und deployen

```bash
# Auf dem Server
cd /opt
git clone https://github.com/deinusername/skrift-backend.git
cd skrift-backend

# .env erstellen (nicht in Git!)
nano .env

# Output-Verzeichnis erstellen
mkdir -p /var/skrift-output
chmod 755 /var/skrift-output

# Starten
docker-compose up -d --build

# Bei Updates einfach:
git pull
docker-compose up -d --build
```

## Nginx Proxy Manager Konfiguration

1. Im Nginx Proxy Manager eine neue "Proxy Host" erstellen:
   - **Domain Names**: `backend.deine-domain.de` (oder Subdomain deiner Wahl)
   - **Scheme**: `http`
   - **Forward Hostname/IP**: `skrift-backend` (Container-Name)
   - **Forward Port**: `4000`
   - **Cache Assets**: aktivieren
   - **Block Common Exploits**: aktivieren
   - **Websockets Support**: deaktivieren

2. SSL-Zertifikat:
   - Tab "SSL" öffnen
   - "Request a new SSL Certificate" auswählen
   - "Force SSL" aktivieren
   - Let's Encrypt Email eingeben

3. Optional - Custom Nginx Configuration:
   ```nginx
   # Größere Request Body Size für große Texte
   client_max_body_size 10M;

   # Timeouts für lange Scriptalizer-Calls
   proxy_connect_timeout 60s;
   proxy_send_timeout 60s;
   proxy_read_timeout 60s;
   ```

## Nützliche Docker-Befehle

```bash
# Container Status prüfen
docker-compose ps

# Logs anzeigen
docker-compose logs -f

# Container neu starten
docker-compose restart

# Container stoppen
docker-compose down

# Container stoppen und Volumes löschen
docker-compose down -v

# In Container-Shell gehen
docker exec -it skrift-backend sh

# Image neu bauen
docker-compose build --no-cache

# Alte Images aufräumen
docker image prune -a
```

## Gesundheits-Check

Nach dem Deployment:

```bash
# Lokal vom Server
curl http://localhost:4000/health

# Über Domain (nach Nginx Proxy Setup)
curl https://backend.deine-domain.de/health

# Sollte zurückgeben:
# {"status":"ok","timestamp":"2026-01-03T..."}
```

## WordPress Integration

In deinem WordPress Plugin (Frontend) die Backend-URL konfigurieren:

```javascript
// WordPress Plugin Einstellungen
const BACKEND_URL = 'https://backend.deine-domain.de';

// API Calls
fetch(`${BACKEND_URL}/api/preview/batch`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sessionId: 'session-uuid',
    letters: [...]
  })
});
```

## N8N Integration

N8N kann die generierten Dateien im `/var/skrift-output` Verzeichnis abholen:

```bash
# N8N Workflow - File Trigger Node
/var/skrift-output/*/order-metadata.json
```

Oder per API:

```bash
# Webhook in N8N, wenn Bestellung fertig ist
POST https://n8n.deine-domain.de/webhook/order-complete
{
  "orderNumber": "SK-2026-01-03-001",
  "path": "/var/skrift-output/SK-2026-01-03-001"
}
```

## Troubleshooting

### Container startet nicht
```bash
# Logs prüfen
docker-compose logs

# Typische Probleme:
# - Fonts fehlen: Fonts-Ordner prüfen
# - Port 4000 belegt: Port in docker-compose.yml ändern
# - .env fehlt: .env Datei erstellen
```

### Fonts werden nicht gefunden
```bash
# In Container prüfen
docker exec -it skrift-backend ls -la /app/fonts

# Sollte zeigen:
# tilda.svg
# alva.svg
# ellie.svg
```

### API antwortet nicht
```bash
# Nginx Proxy Logs prüfen
docker logs nginx-proxy-manager

# Backend Logs prüfen
docker-compose logs skrift-backend

# Firewall prüfen
sudo ufw status
sudo ufw allow 4000/tcp  # Falls direkt ohne Proxy
```

### Durchgestrichene Wörter erscheinen
```bash
# SCRIPTALIZER_ERR_FREQUENCY in .env auf 0 setzen
echo "SCRIPTALIZER_ERR_FREQUENCY=0" >> .env

# Container neu starten
docker-compose restart
```

## Monitoring

### Einfaches Monitoring mit Healthcheck

```bash
# Cronjob erstellen für Health-Check
crontab -e

# Jede 5 Minuten prüfen
*/5 * * * * curl -f http://localhost:4000/health || systemctl restart skrift-backend
```

### Mit Uptime Kuma (empfohlen)

1. Uptime Kuma installieren (auch als Docker Container)
2. HTTP(s) Monitor erstellen für `https://backend.deine-domain.de/health`
3. Alert bei Ausfall per E-Mail/Telegram

## Backup

```bash
# Fonts sichern (einmalig)
tar -czf skrift-fonts-backup.tar.gz /opt/skrift-backend/fonts

# Output-Dateien sichern (täglich via Cronjob)
tar -czf skrift-output-$(date +%Y%m%d).tar.gz /var/skrift-output

# Zu externem Speicher kopieren
rsync -avz /var/skrift-output/ backup-server:/backups/skrift/
```

## Updates

### Update über Docker Hub
```bash
# Neues Image bauen und pushen (lokal)
docker build -t deinusername/skrift-backend:latest .
docker push deinusername/skrift-backend:latest

# Auf Server updaten
docker-compose pull
docker-compose up -d
```

### Update über Git
```bash
# Auf Server
cd /opt/skrift-backend
git pull
docker-compose up -d --build
```

## Sicherheit

- `.env` Datei NIEMALS in Git committen
- Regelmäßig Updates: `docker-compose pull`
- Nginx Proxy Manager für SSL/TLS
- Firewall: Nur notwendige Ports öffnen
- Rate Limiting ist bereits im Backend implementiert
- Regelmäßige Backups der Output-Dateien

## Support

Bei Problemen:
1. Logs prüfen: `docker-compose logs -f`
2. Health-Endpoint testen: `curl http://localhost:4000/health`
3. Container Status: `docker-compose ps`
4. Ins Container-Shell: `docker exec -it skrift-backend sh`