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:

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

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

# 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

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

# 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

# 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

# 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

# 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

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

   # 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

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

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

// 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:

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

Oder per API:

# 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

# 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

# In Container prüfen
docker exec -it skrift-backend ls -la /app/fonts

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

API antwortet nicht

# 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

# 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

# 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

# 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

# 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

# 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