till/managarten
1
0
Fork 0
mirror of https://github.com/Memo-2023/mana-monorepo.git synced 2026-05-14 21:41:09 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
managarten/docs/DEPLOYMENT_HETZNER.md
Till-JS 7abfc4c0b3 docs: add Hetzner deployment guide and update lockfile 
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-27 14:47:35 +01:00

602 lines
22 KiB
Markdown
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Hetzner Deployment Guide
Dieses Dokument beschreibt verschiedene Deployment-Optionen für das Manacore Monorepo auf Hetzner Cloud Infrastructure.
## Inhaltsverzeichnis
- [Bestandsaufnahme](#bestandsaufnahme)
- [Option 1: Single Server](#option-1-single-server-einfach--günstig)
- [Option 2: Dual-Server mit Floating IP](#option-2-dual-server-mit-floating-ip)
- [Option 3: Kubernetes Cluster](#option-3-kubernetes-cluster-enterprise)
- [Option 4: Hybrid mit Docker Swarm](#option-4-hybrid-mit-docker-swarm-empfohlen)
- [Vergleichstabelle](#vergleichstabelle)
- [Empfehlung](#empfehlung)
- [Implementierungsdetails](#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
```yaml
# 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
```yaml
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
```yaml
# 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
```yaml
# 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
```yaml
# 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](./DOCKERFILES.md) - Docker-Konfiguration für alle Services
- [CI_CD.md](./CI_CD.md) - GitHub Actions Pipelines
- [TERRAFORM.md](./TERRAFORM.md) - Infrastructure as Code
- [MONITORING.md](./MONITORING.md) - Prometheus & Grafana Setup
- [BACKUP_STRATEGY.md](./BACKUP_STRATEGY.md) - Backup & Recovery
---
*Erstellt: November 2025*
*Letzte Aktualisierung: November 2025*
Reference in a new issue View git blame Copy permalink