managarten/docs/DEPLOYMENT_HETZNER.md

Hetzner Deployment Guide

Dieses Dokument beschreibt verschiedene Deployment-Optionen für das Manacore Monorepo auf Hetzner Cloud Infrastructure.

Inhaltsverzeichnis

• Bestandsaufnahme
• Option 1: Single Server
• Option 2: Dual-Server mit Floating IP
• Option 3: Kubernetes Cluster
• Option 4: Hybrid mit Docker Swarm
• Vergleichstabelle
• Empfehlung
• Implementierungsdetails

---

Bestandsaufnahme

Zu deployende Komponenten

Typ	Anzahl	Technologie	Deployment-Ziel
Backends	10	NestJS	Container
Web Apps	11	SvelteKit (SSR)	Container
Landing Pages	11	Astro (statisch)	CDN/Static
Auth Service	1	NestJS	Container
Datenbanken	2	PostgreSQL + Redis	Dedicated/Managed
Mobile Apps	10	Expo	App Stores (nicht Hetzner)

Backend-Services im Detail

Service	Package	Port	Datenbank
mana-core-auth	mana-core-auth	3001	PostgreSQL + Redis
Chat Backend	@chat/backend	3002	PostgreSQL
Maerchenzauber Backend	@maerchenzauber/backend	3003	Supabase
Manadeck Backend	@manadeck/backend	3004	Supabase
Picture Backend	@picture/backend	3005	PostgreSQL
Transcriber Backend	@transcriber/backend	3006	Filesystem
Nutriphi Backend	@nutriphi/backend	3007	Supabase
News API	@news/api	3008	PostgreSQL
Quote Backend	@quote/backend	3009	PostgreSQL
Uload Backend	@uload/backend	3010	PostgreSQL

Ressourcenanforderungen (geschätzt)

Komponente	RAM	CPU	Storage
NestJS Backend (pro Service)	200-400 MB	0.25 vCPU	100 MB
SvelteKit Web App (pro App)	150-300 MB	0.25 vCPU	50 MB
PostgreSQL	1-2 GB	1 vCPU	10-50 GB
Redis	256-512 MB	0.25 vCPU	1 GB
Traefik/Nginx	128 MB	0.25 vCPU	100 MB

Gesamt (Minimum): ~8 GB RAM, 4 vCPU, 100 GB Storage

---

Option 1: Single Server (Einfach & Günstig)

Kosten: ~€30-50/Monat

Architektur

┌─────────────────────────────────────────────────────────┐
│                    Hetzner CX41/CX51                     │
│                   (8 vCPU, 16-32 GB RAM)                │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Traefik   │  │   Docker    │  │  PostgreSQL │     │
│  │  (Reverse   │  │  Compose    │  │    Redis    │     │
│  │   Proxy)    │  │  (All Apps) │  │             │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
│                                                          │
│  Backends: 10 Container (~200MB RAM each)               │
│  Web Apps: 10 Container (SSR)                           │
│  Landing: Statisch via Traefik                          │
└─────────────────────────────────────────────────────────┘

Hetzner Server Empfehlung

Server	vCPU	RAM	Storage	Preis
CX41	8	16 GB	160 GB	~€28/Monat
CX51	16	32 GB	240 GB	~€58/Monat

Vorteile

• Einfache Verwaltung
• Günstig
• Schnelle Einrichtung
• Ein Server = ein Backup

Nachteile

• Kein Failover (Single Point of Failure)
• Downtime bei Updates
• Keine horizontale Skalierung
• Server-Ausfall = kompletter Ausfall

Wann geeignet?

• Entwicklung/Staging
• MVP/Early Stage
• Budget-kritische Projekte
• Wenig Traffic (<1000 DAU)

---

Option 2: Dual-Server mit Floating IP

Kosten: ~€80-120/Monat

Architektur

                    ┌─────────────────┐
                    │  Floating IP    │
                    │  (Failover)     │
                    └────────┬────────┘
                             │
              ┌──────────────┴──────────────┐
              │                             │
    ┌─────────▼─────────┐       ┌──────────▼─────────┐
    │   Server 1 (CX31) │       │   Server 2 (CX31)  │
    │   PRIMARY         │       │   STANDBY          │
    ├───────────────────┤       ├────────────────────┤
    │ • Traefik         │       │ • Traefik          │
    │ • All Backends    │◄─────►│ • All Backends     │
    │ • Web Apps        │ sync  │ • Web Apps         │
    │ • PostgreSQL      │       │ • PostgreSQL       │
    │   (Primary)       │       │   (Replica)        │
    │ • Redis           │       │ • Redis Sentinel   │
    └───────────────────┘       └────────────────────┘
              │                             │
              └──────────────┬──────────────┘
                             │
                    ┌────────▼────────┐
                    │  Hetzner Volume │
                    │  (Shared Data)  │
                    └─────────────────┘

Komponenten

Komponente	Funktion
Floating IP	Virtuelle IP, die zwischen Servern wechseln kann
Keepalived	VRRP-Daemon für automatisches Failover
PostgreSQL Streaming Replication	Echtzeit-Datenbank-Replikation
Redis Sentinel	Redis High Availability
Litestream/pgBackRest	Kontinuierliche Backups

Server-Konfiguration

# Server 1 & 2 identisch
Server: CX31
vCPU: 4
RAM: 8 GB
Storage: 80 GB
Kosten: ~€15/Monat pro Server

# Zusätzlich
Floating IP: €4/Monat
Volume (100GB): €4.40/Monat

Failover-Prozess

1. Keepalived erkennt Server-Ausfall (Health Check)
2. Floating IP wird auf Standby-Server umgeleitet (~30 Sekunden)
3. PostgreSQL Replica wird zu Primary promoted
4. Redis Sentinel wählt neuen Master

Vorteile

• Automatisches Failover (~30 Sekunden)
• Keine Downtime bei Updates (Rolling)
• Datenbank-Replikation
• Gutes Preis-Leistungs-Verhältnis

Nachteile

• Mehr Komplexität als Single Server
• PostgreSQL Failover kann komplex sein
• Keepalived-Konfiguration erforderlich

Wann geeignet?

• Produktions-Workloads
• 99.9% Uptime-Anforderung
• Mittlerer Traffic (1000-10000 DAU)

---

Option 3: Kubernetes Cluster (Enterprise)

Kosten: ~€150-300/Monat

Architektur

                         ┌─────────────────┐
                         │  Hetzner LB     │
                         │  (Cloud-native) │
                         └────────┬────────┘
                                  │
        ┌─────────────────────────┼─────────────────────────┐
        │                         │                         │
┌───────▼───────┐       ┌────────▼────────┐       ┌────────▼───────┐
│   Node 1      │       │    Node 2       │       │    Node 3      │
│   (CX21)      │       │    (CX21)       │       │    (CX21)      │
├───────────────┤       ├─────────────────┤       ├────────────────┤
│  k3s Worker   │       │   k3s Worker    │       │  k3s Worker    │
│  • Pods       │       │   • Pods        │       │  • Pods        │
│  • Services   │       │   • Services    │       │  • Services    │
└───────────────┘       └─────────────────┘       └────────────────┘
        │                         │                         │
        └─────────────────────────┼─────────────────────────┘
                                  │
                    ┌─────────────┴─────────────┐
                    │                           │
           ┌────────▼────────┐       ┌──────────▼─────────┐
           │ Hetzner Managed │       │  Hetzner Volume    │
           │ PostgreSQL      │       │  (Persistent)      │
           │ (Optional)      │       │                    │
           └─────────────────┘       └────────────────────┘

Kubernetes Stack

Cluster:
  - k3s (leichtgewichtiges Kubernetes)
  - 3 Nodes minimum für HA Control Plane

Ingress:
  - Traefik (in k3s integriert)
  - oder NGINX Ingress Controller

TLS:
  - cert-manager
  - Let's Encrypt (automatische Zertifikate)

Storage:
  - Longhorn (Distributed Block Storage)
  - oder Hetzner CSI Driver

GitOps:
  - ArgoCD oder Flux
  - Automatische Deployments aus Git

Monitoring:
  - Prometheus
  - Grafana
  - Alertmanager

Logging:
  - Loki
  - Promtail

Server-Konfiguration

# k3s Nodes
3x CX21:
  vCPU: 2
  RAM: 4 GB
  Storage: 40 GB
  Kosten: ~€6/Monat pro Node = €18/Monat

# Oder für mehr Ressourcen
3x CX31:
  vCPU: 4
  RAM: 8 GB
  Storage: 80 GB
  Kosten: ~€15/Monat pro Node = €45/Monat

# Load Balancer
Hetzner LB: €5/Monat

# Volumes für Persistent Storage
3x 50GB Volumes: ~€7/Monat

Vorteile

• Auto-Scaling (Horizontal Pod Autoscaler)
• Self-Healing (automatischer Pod-Restart)
• Rolling Updates ohne Downtime
• Deklarative Konfiguration
• Multi-Zone möglich
• Industry Standard

Nachteile

• Hohe Komplexität
• Steile Lernkurve
• Overhead für kleine Teams
• Mehr Ressourcen für Control Plane

Wann geeignet?

• Enterprise-Anforderungen
• Großes Team mit K8s-Erfahrung
• Hoher Traffic (>10000 DAU)
• Microservices-Architektur
• Multi-Tenant-Anforderungen

---

Option 4: Hybrid mit Docker Swarm (Empfohlen)

Kosten: ~€100-150/Monat

Architektur

┌─────────────────────────────────────────────────────────────────┐
│                        HETZNER CLOUD                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   ┌─────────────────┐              ┌─────────────────┐          │
│   │  Load Balancer  │              │   Cloud Firewall │          │
│   │   (Hetzner LB)  │              │                  │          │
│   └────────┬────────┘              └──────────────────┘          │
│            │                                                     │
│   ┌────────┴────────────────────────────────┐                   │
│   │                                          │                   │
│   ▼                                          ▼                   │
│ ┌──────────────────┐              ┌──────────────────┐          │
│ │   App Server 1   │              │   App Server 2   │          │
│ │     (CX31)       │              │     (CX31)       │          │
│ ├──────────────────┤              ├──────────────────┤          │
│ │ Docker Swarm     │◄────────────►│ Docker Swarm     │          │
│ │ Manager + Worker │    Overlay   │ Manager + Worker │          │
│ │                  │    Network   │                  │          │
│ │ • All Backends   │              │ • All Backends   │          │
│ │ • Web Apps       │              │ • Web Apps       │          │
│ │ • Traefik        │              │ • Traefik        │          │
│ └──────────────────┘              └──────────────────┘          │
│            │                                │                    │
│            └────────────────┬───────────────┘                   │
│                             │                                    │
│                    ┌────────▼────────┐                          │
│                    │   DB Server     │                          │
│                    │    (CX21)       │                          │
│                    ├─────────────────┤                          │
│                    │ • PostgreSQL 16 │                          │
│                    │ • Redis 7       │                          │
│                    │ • Daily Backups │                          │
│                    │   → Object      │                          │
│                    │     Storage     │                          │
│                    └─────────────────┘                          │
│                                                                  │
│   ┌─────────────────────────────────────────────────────┐       │
│   │              Hetzner Object Storage                  │       │
│   │         (Backups, Static Assets, Media)              │       │
│   └─────────────────────────────────────────────────────┘       │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

                              │
                              ▼
              ┌───────────────────────────────┐
              │        EXTERNAL CDN           │
              │      (Cloudflare Free)        │
              │  • Static Assets              │
              │  • DDoS Protection            │
              │  • SSL Termination            │
              └───────────────────────────────┘

Warum Docker Swarm?

Docker Swarm bietet die wichtigsten Features von Kubernetes mit deutlich weniger Komplexität:

Feature	Docker Swarm	Kubernetes
Lernkurve	Niedrig	Hoch
Setup-Zeit	Minuten	Stunden/Tage
Service Discovery	Built-in	Benötigt Config
Load Balancing	Built-in	Benötigt Ingress
Rolling Updates	Built-in	Built-in
Secrets Management	Built-in	Built-in
Ressourcen-Overhead	Minimal	Signifikant

Server-Konfiguration

# App Server 1 & 2
2x CX31:
  vCPU: 4
  RAM: 8 GB
  Storage: 80 GB
  Kosten: €15/Monat × 2 = €30/Monat

# Database Server
1x CX21:
  vCPU: 2
  RAM: 4 GB
  Storage: 40 GB + 100GB Volume
  Kosten: €6/Monat + €4.40/Monat = €10.40/Monat

# Load Balancer
Hetzner LB:
  Kosten: €5/Monat

# Object Storage (Backups)
100 GB:
  Kosten: ~€5/Monat

# Cloud Firewall
Kostenlos

# Private Network
Kostenlos

─────────────────────────────
Gesamt: ~€50-55/Monat Basis
        + Traffic-Kosten

Docker Swarm Stack

# docker-stack.yml
version: "3.8"

services:
  # Reverse Proxy
  traefik:
    image: traefik:v3.0
    deploy:
      replicas: 2
      placement:
        constraints:
          - node.role == manager
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - traefik-certs:/letsencrypt

  # Auth Service
  mana-core-auth:
    image: ghcr.io/your-org/mana-core-auth:latest
    deploy:
      replicas: 2
      update_config:
        parallelism: 1
        delay: 10s
        failure_action: rollback
      restart_policy:
        condition: on-failure
    environment:
      - DATABASE_URL=postgresql://...
    labels:
      - "traefik.http.routers.auth.rule=Host(`auth.yourdomain.com`)"

  # Backend Services (repeat for each)
  chat-backend:
    image: ghcr.io/your-org/chat-backend:latest
    deploy:
      replicas: 2
    labels:
      - "traefik.http.routers.chat-api.rule=Host(`api.chat.yourdomain.com`)"

  # Web Apps (repeat for each)
  chat-web:
    image: ghcr.io/your-org/chat-web:latest
    deploy:
      replicas: 2
    labels:
      - "traefik.http.routers.chat-web.rule=Host(`chat.yourdomain.com`)"

volumes:
  traefik-certs:

networks:
  default:
    driver: overlay
    attachable: true

Vorteile

• Einfacher als Kubernetes
• Native Docker-Erfahrung nutzbar
• Built-in Service Discovery & Load Balancing
• Rolling Updates ohne Downtime
• Overlay-Network für sichere Kommunikation
• Hetzner LB für echte HA

Nachteile

• Weniger Features als Kubernetes
• Kleineres Ökosystem
• Kein HPA (Horizontal Pod Autoscaler)

Wann geeignet?

• Produktions-Workloads
• Kleine bis mittlere Teams
• Docker-Erfahrung vorhanden
• Mittlerer Traffic (1000-50000 DAU)

---

Vergleichstabelle

Feature	Option 1	Option 2	Option 3	Option 4
Kosten/Monat	€30-50	€80-120	€150-300	€100-150
Ausfallsicherheit	❌	✅	✅✅	✅
Auto-Failover	❌	✅ (30s)	✅ (<10s)	✅ (10-30s)
Komplexität	Niedrig	Mittel	Hoch	Mittel
Skalierbarkeit	❌	⚠️	✅✅	✅
Zero-Downtime Deploy	❌	✅	✅	✅
Wartungsaufwand	Niedrig	Mittel	Hoch	Mittel
Backup/Recovery	Manuell	Auto	Auto	Auto
Setup-Zeit	1 Tag	2-3 Tage	1 Woche	2-3 Tage
Team-Größe	1 Person	1-2 Personen	2+ Personen	1-2 Personen

---

Empfehlung

Für Manacore Monorepo: Option 4 (Hybrid mit Docker Swarm)

Begründung:

1. Richtige Balance zwischen Komplexität und Features
2. Docker Swarm ist deutlich einfacher als Kubernetes, bietet aber:
   • Service Discovery
   • Load Balancing
   • Rolling Updates
   • Health Checks
   • Secrets Management
3. Hetzner Load Balancer für echte HA ohne komplexe Floating-IP-Konfiguration
4. Separater DB-Server für:
   • Bessere Performance
   • Einfachere Backups
   • Unabhängige Skalierung
5. Cloudflare als kostenloses CDN + DDoS-Schutz
6. Object Storage für Backups und Media-Dateien

Migrationspfad

Option 1 (Dev/Staging)
        ↓
Option 4 (Production)
        ↓
Option 3 (bei Bedarf für Enterprise-Scale)

---

Implementierungsdetails

Nächste Schritte

1. Dockerfiles erstellen für alle Services
2. CI/CD Pipeline mit GitHub Actions
3. Hetzner Infrastruktur provisionieren (Terraform)
4. Docker Swarm einrichten
5. Monitoring mit Prometheus/Grafana
6. Backup-Strategie implementieren

Geschätzte Implementierungszeit

Phase	Dauer	Beschreibung
Dockerfiles	2-3 Tage	Alle Services containerisieren
CI/CD	1-2 Tage	GitHub Actions Pipelines
Infrastruktur	1 Tag	Hetzner Setup (Terraform)
Swarm Setup	1 Tag	Cluster initialisieren
Deployment	1-2 Tage	Services deployen & testen
Monitoring	1 Tag	Prometheus, Grafana, Alerts
Gesamt	~1-2 Wochen

---

Weiterführende Dokumente

• DOCKERFILES.md - Docker-Konfiguration für alle Services
• CI_CD.md - GitHub Actions Pipelines
• TERRAFORM.md - Infrastructure as Code
• MONITORING.md - Prometheus & Grafana Setup
• BACKUP_STRATEGY.md - Backup & Recovery

---

Erstellt: November 2025 Letzte Aktualisierung: November 2025