till/managarten
1
0
Fork 0
mirror of https://github.com/Memo-2023/mana-monorepo.git synced 2026-05-14 18:41:08 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

docs: add Hetzner deployment guide and update lockfile

Browse source 
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Till-JS 2025-11-27 14:47:35 +01:00
parent cc6ca028a7
commit 7abfc4c0b3
2 changed files with 1778 additions and 467 deletions
Download patch file Download diff file Expand all files Collapse all files

602
docs/DEPLOYMENT_HETZNER.md Normal file
View file

@ -0,0 +1,602 @@
# 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*

1643
pnpm-lock.yaml generated
View file

File diff suppressed because it is too large Load diff