Inhaltsverzeichnis

1. Überblick: Was soll das System tun?
2. Anforderungen
3. Problemstellung: Warum brauchen wir diese Architektur?
   • 3.1 Problem 1: Datenbank-Performance als Flaschenhals
   • 3.2 Problem 2: Single Point of Failure
   • 3.3 Problem 3: Skalierbarkeits-Limits
   • 3.4 Problem 4: Latenz und Benutzererfahrung
4. System-Architektur
   • 4.1 Komponenten-Übersicht
   • 4.2 Datenbank-Design
   • 4.3 Short-Code-Generierung
   • 4.4 API-Endpunkte
     • 4.4.1 POST /api/shorten
     • 4.4.2 GET /{short_code}
5. Redis-Caching-Strategie: Warum und wie?
   • 5.1 Warum Redis? Das Performance-Problem verstehen
   • 5.2 Was macht Redis genau?
   • 5.3 Cache-Strategien im Detail
   • 5.4 Redis-Konfiguration und Memory-Management
   • 5.5 Redis-Cluster für hohe Verfügbarkeit
6. Load Balancing: Was macht ein Load-Balancer genau?
   • 6.1 Das Problem: Warum brauchen wir einen Load-Balancer?
   • 6.2 Was macht ein Load-Balancer genau?
   • 6.3 Load-Balancing-Algorithmen
   • 6.4 Health Checks: Warum sind sie kritisch?
   • 6.5 Session-Persistenz (Sticky Sessions)
   • 6.6 SSL/TLS Termination
   • 6.7 Rate Limiting und DDoS-Schutz
   • 6.8 Traefik-Konfiguration: Vollständiges Beispiel
   • 6.9 Monitoring und Metriken
7. Skalierbarkeit: Warum horizontale Skalierung?
   • 7.1 Das Problem: Vertikale vs. Horizontale Skalierung
   • 7.2 Warum horizontale Skalierung für unseren URL-Shortener?
   • 7.3 Anforderungen für horizontale Skalierung
   • 7.4 Skalierung in der Praxis
   • 7.5 Skalierungs-Limits und Bottlenecks
   • 7.6 Skalierungsschritte: Praktisches Beispiel
   • 7.7 Monitoring der Skalierung
8. Erweiterte Optimierungen
9. Zusammenfassung

Überblick: Was soll das System tun?

Am Anfang überlegen wir uns wie wir generell die Short-URLs Designen. Dazu beginnen wir was eigentlich gemacht werden soll:

1. User gibt eine lange URL ein
2. Die URL wird von einem API-Endpunkt entgegen genommen und gibt eine Short-URL zurück und speichert die Short-URL in einer Datenbank
3. Der User ruft die Short-URL auf, es wird in einer Datenbank nachgeschaut ob die Short-URL vorhanden ist, holt die Value und schickt den Nutzer mit einem HTTP-301 weiter.

Anforderungen

• Der Short-Code sollte maximal 7 Zeichen lang sein. Mit einer Base64-Konvertierung haben wir kein Problem mit doppelten Indexen.
• Die Server sollten horizontal Skalierbar sein, dazu ist wichtig das ein Load-Balancer (am besten Traefik) die Last verteilt.
• Damit man keine doppelten Short-URLs erstellt sollte man einen Redis nutzen um die Datenbank zu cachen und so anfragen schneller umzusetzen.

Problemstellung: Warum brauchen wir diese Architektur?

Bevor wir in die Details gehen, müssen wir verstehen, welche Probleme wir lösen müssen. Ein naives System mit nur einem Server und einer Datenbank würde bei steigender Last schnell an seine Grenzen stoßen.

Problem 1: Datenbank-Performance als Flaschenhals

Das Problem: Stellen Sie sich vor, Sie haben 10.000 Anfragen pro Sekunde für Redirects. Jede Anfrage muss:

1. Eine Datenbankverbindung aufbauen (5-10ms Overhead)
2. Eine SQL-Query ausführen (10-50ms je nach Last)
3. Das Ergebnis zurückgeben

Bei 10.000 Anfragen/Sekunde bedeutet das:

• Ohne Cache: 10.000 × 50ms = 500 Sekunden Gesamtzeit → System bricht zusammen
• Mit Cache (Redis): 9.500 × 0.1ms (Cache-Hit) + 500 × 50ms (Cache-Miss) = 25 Sekunden → System läuft stabil

Die Lösung: Redis als In-Memory-Cache reduziert Datenbankzugriffe um 95-99%.

Problem 2: Single Point of Failure

Das Problem: Ein einzelner Server kann:

• Ausfallen (Hardware-Fehler, Software-Crash)
• Überlastet werden (CPU/Memory-Limits erreicht)
• Wartungsarbeiten erfordern (Updates, Patches)

Wenn dieser eine Server ausfällt, ist die gesamte Anwendung offline.

Die Lösung: Mehrere Server (horizontale Skalierung) + Load-Balancer sorgen für:

• Hochverfügbarkeit: Wenn ein Server ausfällt, übernehmen die anderen
• Lastverteilung: Kein einzelner Server wird überlastet
• Wartbarkeit: Server können einzeln aktualisiert werden

Problem 3: Skalierbarkeits-Limits

Das Problem: Ein einzelner Server hat physikalische Limits:

• CPU: Maximal 32-64 Cores pro Server
• Memory: Maximal 512GB-1TB RAM
• Netzwerk: Maximal 10-100 Gbps

Wenn Sie wachsen, müssen Sie entweder:

• Vertikal skalieren: Größere, teurere Server kaufen (sehr teuer, schnell an Limits)
• Horizontal skalieren: Mehr günstige Server hinzufügen (kosteneffizient, praktisch unbegrenzt)

Die Lösung: Horizontale Skalierung mit Load-Balancer ermöglicht praktisch unbegrenztes Wachstum.

Problem 4: Latenz und Benutzererfahrung

Das Problem: Benutzer erwarten Antwortzeiten unter 100ms. Bei einer Datenbank-Query:

• Lokale Datenbank: 5-20ms
• Remote-Datenbank: 20-100ms (abhängig von Netzwerk-Latenz)
• Bei hoher Last: 100-1000ms+ (Datenbank wird zum Flaschenhals)

Die Lösung: Redis liefert Antworten in <1ms, was die Benutzererfahrung drastisch verbessert.

System-Architektur

Wichtiger Hinweis: Alle Code-Beispiele in diesem Tutorial sind vereinfachte Meta-Code-Beispiele zur Veranschaulichung der Konzepte und Logik. Sie dienen dem Verständnis der System-Architektur und sind nicht als vollständige, produktionsreife Implementierungen gedacht. In einer produktiven Umgebung wären zusätzlich zu berücksichtigen: umfassende Fehlerbehandlung, Input-Validierung, Security-Best-Practices, Logging, Monitoring, Connection-Pooling, Migrationen, Tests, Dokumentation und viele weitere Aspekte.

Komponenten-Übersicht

Unser System besteht aus folgenden Komponenten:

┌─────────────┐
│   Client    │
└──────┬──────┘
       ▼
┌─────────────────┐
│  Load Balancer  │
└──────┬──────────┘
       ├──────────────┬──────────────┐
       ▼              ▼              ▼
┌──────────┐   ┌──────────┐   ┌──────────┐
│  API-1   │   │  API-2   │   │  API-3   │  (Horizontale Skalierung)
└────┬─────┘   └────┬─────┘   └────┬─────┘
     └──────┬───────┴──────┬───────┘
            ▼              ▼
      ┌─────────┐    ┌─────────┐
      │  Cache  │    │   DB    │  
      └─────────┘    └─────────┘

1. Datenbank-Design

Hinweis: Die folgenden Code-Beispiele sind vereinfachte Meta-Code-Beispiele zur Veranschaulichung der Konzepte. In einer produktiven Umgebung wären zusätzliche Aspekte wie Fehlerbehandlung, Validierung, Migrationen etc. zu berücksichtigen.

Zuerst müssen wir die Datenbank-Struktur definieren. Wir benötigen eine Tabelle für die URL-Mappings:

SQL Schema (Meta-Code Beispiel):

-- Vereinfachtes Schema zur Veranschaulichung
-- In Produktion: Weitere Indizes, Constraints, Partitionierung etc.

CREATE TABLE url_mappings (
    id BIGSERIAL PRIMARY KEY,                    -- Eindeutige ID
    short_code VARCHAR(7) UNIQUE NOT NULL,       -- 7-stelliger Code
    original_url TEXT NOT NULL,                  -- Original-URL
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    access_count BIGINT DEFAULT 0,                -- Optional: Analytics
    INDEX idx_short_code (short_code)            -- Index für schnelle Lookups
);

Wichtige Überlegungen:

• short_code ist eindeutig und indiziert für schnelle Lookups
• original_url speichert die vollständige URL
• access_count für Analytics (optional)
• In Produktion: Weitere Optimierungen wie Partitionierung, Read-Replicas etc.

2. Short-Code-Generierung

Der Short-Code wird aus einer eindeutigen ID generiert. Hier ist ein vereinfachtes Meta-Code-Beispiel:

Meta-Code Beispiel (Python-ähnlich):

# Vereinfachtes Beispiel zur Veranschaulichung
# In Produktion: Kollisionsprüfung, Retry-Logik etc.

import base64
import hashlib

def generate_short_code(url_id: int) -> str:
    """
    Generiert einen 7-stelligen Base64-kodierten Short-Code
    aus einer numerischen ID.
    
    Logik:
    1. Konvertiere ID zu Bytes
    2. Base64-kodiere
    3. Kürze auf 7 Zeichen
    """
    id_bytes = url_id.to_bytes(8, byteorder='big')
    encoded = base64.urlsafe_b64encode(id_bytes).decode('utf-8')
    short_code = encoded[:7].rstrip('=')
    return short_code

# Alternative: Hash-basiert (für bessere Verteilung)
def generate_short_code_from_url(url: str, salt: str = "") -> str:
    """
    Generiert einen Short-Code aus der URL selbst.
    Vorteil: Deterministisch (gleiche URL = gleicher Code)
    """
    hash_input = (url + salt).encode('utf-8')
    hash_bytes = hashlib.sha256(hash_input).digest()[:5]
    encoded = base64.urlsafe_b64encode(hash_bytes).decode('utf-8')
    return encoded[:7].rstrip('=')

3. API-Endpunkte

Hinweis: Die folgenden Code-Beispiele sind vereinfachte Meta-Code-Beispiele zur Veranschaulichung der Logik. In Produktion wären zusätzlich zu implementieren: Input-Validierung, Rate-Limiting, umfassende Fehlerbehandlung, Logging, Monitoring, Connection-Pooling etc.

POST /api/shorten

API-Spezifikation:

Request:

{
  "url": "https://www.example.com/very/long/url/path"
}

Response:

{
  "short_code": "aB3dEfG",
  "short_url": "https://short.ly/aB3dEfG",
  "original_url": "https://www.example.com/very/long/url/path"
}

Meta-Code Implementierung (vereinfacht):

# Meta-Code: Vereinfachtes Beispiel zur Veranschaulichung der Logik
# Framework-agnostisch dargestellt

@app.route('/api/shorten', methods=['POST'])
def shorten_url():
    # 1. Request-Daten extrahieren
    original_url = request.get_json()['url']
    
    # 2. Cache-Check: Existiert bereits ein Short-Code für diese URL?
    cache_key = f"url:{original_url}"
    cached_code = redis.get(cache_key)
    
    if cached_code:
        # Cache-Hit: Gebe existierenden Code zurück
        return {
            'short_code': cached_code,
            'short_url': f'https://short.ly/{cached_code}',
            'original_url': original_url
        }
    
    # 3. Cache-Miss: Erstelle neuen Eintrag
    # 3a. Generiere Short-Code
    url_id = db.get_next_id()  # Oder Auto-Increment
    short_code = generate_short_code(url_id)
    
    # 3b. Speichere in Datenbank
    db.insert('url_mappings', {
        'short_code': short_code,
        'original_url': original_url
    })
    
    # 3c. Cache speichern (beide Richtungen)
    redis.setex(f"url:{original_url}", 3600, short_code)
    redis.setex(f"code:{short_code}", 86400, original_url)
    
    # 4. Response zurückgeben
    return {
        'short_code': short_code,
        'short_url': f'https://short.ly/{short_code}',
        'original_url': original_url
    }

Logik-Flow:

1. Cache-Check: Prüfe ob URL bereits existiert → verhindert Duplikate
2. Code-Generierung: Erstelle neuen eindeutigen Short-Code
3. Datenbank-Speicherung: Persistiere Mapping
4. Cache-Update: Speichere in beide Richtungen für schnelle Lookups

GET /{short_code}

API-Spezifikation:

Request:

GET /abc123

Response:

HTTP 301 Redirect
Location: https://www.example.com/very/long/url/path

Meta-Code Implementierung (vereinfacht):

# Meta-Code: Vereinfachtes Beispiel zur Veranschaulichung der Logik

@app.route('/<short_code>', methods=['GET'])
def redirect_to_url(short_code):
    # 1. Cache-Check: Ist URL im Cache?
    cache_key = f"code:{short_code}"
    cached_url = redis.get(cache_key)
    
    if cached_url:
        # Cache-Hit: Sofortiger Redirect (sehr schnell: <1ms)
        return redirect(cached_url, code=301)
    
    # 2. Cache-Miss: Hole aus Datenbank
    original_url = db.query(
        "SELECT original_url FROM url_mappings WHERE short_code = ?",
        short_code
    )
    
    if not original_url:
        return error(404, 'Short URL not found')
    
    # 3. Cache für zukünftige Anfragen speichern
    redis.setex(cache_key, 86400, original_url)  # 24 Stunden
    
    # 4. Optional: Access-Count asynchron aktualisieren
    # (Nicht blockierend, läuft im Hintergrund)
    async_update_access_count(short_code)
    
    # 5. Redirect zurückgeben
    return redirect(original_url, code=301)

Logik-Flow:

1. Cache-Check: Prüfe ob Short-Code im Cache → 95-99% der Fälle
2. Datenbank-Fallback: Falls nicht im Cache → Hole aus DB
3. Cache-Update: Speichere für zukünftige Anfragen
4. Redirect: HTTP 301 Permanent Redirect zur Original-URL

4. Redis-Caching-Strategie: Warum und wie?

Warum Redis? Das Performance-Problem verstehen

Ohne Redis (nur Datenbank):

Anfrage → API-Server → Datenbank-Query (50ms) → Antwort

Bei 10.000 Anfragen/Sekunde:

• Datenbank muss 10.000 Queries/Sekunde verarbeiten
• Jede Query benötigt 50ms → Datenbank wird überlastet
• System bricht zusammen oder wird extrem langsam

Mit Redis (Cache-Layer):

Anfrage → API-Server → Redis-Cache (0.1ms) → Antwort
         ↓ (Cache-Miss, 5% der Fälle)
         → Datenbank-Query (50ms) → Cache speichern → Antwort

Bei 10.000 Anfragen/Sekunde:

• 9.500 Anfragen aus Cache (0.1ms) = 0.95 Sekunden
• 500 Anfragen aus Datenbank (50ms) = 25 Sekunden
• Gesamt: ~26 Sekunden statt 500 Sekunden = 95% Performance-Gewinn

Was macht Redis genau?

Redis ist ein In-Memory-Datenbank (alle Daten im RAM), was sie extrem schnell macht:

Warum ist Redis so schnell?

1. Keine Festplatten-I/O: Alles im RAM (1000x schneller als SSD)
2. Einfache Datenstrukturen: Key-Value-Store ohne komplexe Joins
3. Single-threaded: Keine Locks, keine Race-Conditions
4. Optimiert für Geschwindigkeit: C-Implementierung, minimaler Overhead

Cache-Strategien im Detail

Redis wird für zwei kritische Zwecke verwendet:

1. URL → Short-Code Cache (Verhindert Duplikate)

Problem ohne Cache:

# User sendet gleiche URL zweimal
POST /api/shorten {"url": "https://example.com"}
→ Datenbank-Query: "SELECT * WHERE url = ..." (50ms)
→ Nicht gefunden → Neuer Eintrag erstellt

POST /api/shorten {"url": "https://example.com"}  # Gleiche URL!
→ Datenbank-Query: "SELECT * WHERE url = ..." (50ms)
→ Nicht gefunden → Noch ein Eintrag erstellt (DUPLIKAT!)

Lösung mit Cache:

# Erste Anfrage
POST /api/shorten {"url": "https://example.com"}
→ Redis-Check: "GET url:https://example.com" (0.1ms)
→ Nicht gefunden → Datenbank → Cache speichern
→ Redis: "SETEX url:https://example.com 3600 abc123"

# Zweite Anfrage (gleiche URL)
POST /api/shorten {"url": "https://example.com"}
→ Redis-Check: "GET url:https://example.com" (0.1ms)
→ Gefunden! → Sofort zurückgeben (keine Datenbank-Query)

2. Short-Code → URL Cache (Beschleunigt Redirects)

Das Problem: Redirects sind der häufigste Operationstyp (99% aller Anfragen). Jeder Redirect ohne Cache bedeutet:

• Datenbankverbindung aufbauen
• SQL-Query ausführen
• Ergebnis zurückgeben

Bei 1 Million Redirects/Tag = 11.5 Redirects/Sekunde → Datenbank wird überlastet.

Die Lösung:

# Redirect-Anfrage
GET /abc123
→ Redis: "GET code:abc123" (0.1ms)
→ Gefunden! → Sofortiger Redirect (keine Datenbank-Query)

Cache-Hit-Rate Optimierung:

Eine gute Cache-Hit-Rate liegt bei 95-99%. Das bedeutet:

• 95-99% der Anfragen werden aus Cache bedient (<1ms)
• 1-5% der Anfragen gehen zur Datenbank (50ms)

Cache-Strategie im Code (Meta-Code Beispiel):

# Meta-Code: Vereinfachtes Beispiel zur Veranschaulichung
# Cache-Aside Pattern: Cache wird "neben" der Datenbank verwendet

# Beim Erstellen einer Short-URL
# Cache in beide Richtungen für schnelle Lookups
redis.setex(f"url:{original_url}", 3600, short_code)      # URL → Code (1 Stunde)
redis.setex(f"code:{short_code}", 86400, original_url)    # Code → URL (24 Stunden)

# Beim Abrufen (Cache-Aside Pattern)
def get_url_from_cache_or_db(short_code):
    # 1. Prüfe Cache zuerst (schnell: <1ms)
    cached_url = redis.get(f"code:{short_code}")
    if cached_url:
        return cached_url  # Cache-Hit: Sofort zurückgeben
    
    # 2. Cache-Miss: Hole aus Datenbank (langsam: 50ms)
    url = db.query("SELECT original_url WHERE short_code = ?", short_code)
    
    # 3. Speichere im Cache für zukünftige Anfragen
    if url:
        redis.setex(f"code:{short_code}", 86400, url)
    
    return url

Redis-Konfiguration und Memory-Management

Warum Memory-Limits wichtig sind:

Redis speichert alles im RAM. Ohne Limits würde Redis:

• Den gesamten verfügbaren RAM verbrauchen
• Das System zum Absturz bringen
• Andere Anwendungen verdrängen

Redis-Konfiguration (redis.conf):

# Maximal 2GB RAM für Redis
maxmemory 2gb

# Eviction-Policy: Welche Keys werden gelöscht wenn Memory voll ist?
# allkeys-lru: Löscht am wenigsten genutzte Keys (LRU = Least Recently Used)
maxmemory-policy allkeys-lru

# Alternative Policies:
# - noeviction: Keine Keys löschen (Fehler wenn voll)
# - allkeys-lfu: Löscht am wenigsten häufig genutzte Keys
# - volatile-lru: Löscht nur Keys mit TTL

TTL (Time-To-Live) Strategie (Meta-Code Beispiel):

# Meta-Code: Beispiel für unterschiedliche TTL-Strategien
# TTL bestimmt, wie lange Daten im Cache bleiben

# Kurze TTL für selten genutzte/temporäre Daten
redis.setex("temp:session:123", 300, data)              # 5 Minuten

# Mittlere TTL für normale Daten
redis.setex("url:https://example.com", 3600, code)       # 1 Stunde

# Lange TTL für häufig genutzte, stabile Daten
redis.setex("code:abc123", 86400, url)                   # 24 Stunden

Warum unterschiedliche TTLs?

• Kurze TTL: Daten ändern sich häufig oder sind temporär
• Lange TTL: Daten ändern sich selten, hohe Cache-Hit-Rate gewünscht
• Strategie: Balance zwischen Cache-Hit-Rate und Datenkonsistenz

Redis-Cluster für hohe Verfügbarkeit

Problem: Single Redis-Instanz

Wenn Redis ausfällt:

• Alle Cache-Daten sind weg
• System fällt auf Datenbank zurück (langsam)
• Bei hoher Last: System kann zusammenbrechen

Lösung: Redis-Cluster oder Redis-Sentinel

┌─────────┐    ┌─────────┐    ┌─────────┐
│ Redis-1 │    │ Redis-2 │    │ Redis-3 │
│ (Master)│◄───┤(Replica)│◄───┤(Replica)│
└─────────┘    └─────────┘    └─────────┘
     │              │              │
     └──────────────┴──────────────┘
                    │
              ┌─────────┐
              │ Sentinel│  (Überwacht Master, failover bei Ausfall)
              └─────────┘

Vorteile:

• Hochverfügbarkeit: Wenn Master ausfällt, übernimmt Replica
• Read-Skalierung: Replicas können für Reads genutzt werden
• Datenredundanz: Daten sind auf mehreren Servern gespeichert

5. Load Balancing: Was macht ein Load-Balancer genau?

Das Problem: Warum brauchen wir einen Load-Balancer?

Ohne Load-Balancer (ein Server):

Client → API-Server (10.000 Anfragen/Sekunde)

Probleme:

1. Single Point of Failure: Wenn Server ausfällt, ist alles offline
2. Performance-Limit: Ein Server kann nur begrenzte Anfragen verarbeiten
3. Wartungsprobleme: Server muss offline für Updates
4. Ressourcen-Limit: CPU/Memory-Limits werden erreicht

Mit Load-Balancer (mehrere Server):

Client → Load-Balancer → API-Server-1 (3.333 Anfragen/Sekunde)
                       → API-Server-2 (3.333 Anfragen/Sekunde)
                       → API-Server-3 (3.333 Anfragen/Sekunde)

Vorteile:

1. Hochverfügbarkeit: Wenn ein Server ausfällt, übernehmen die anderen
2. Skalierbarkeit: Mehr Server = mehr Kapazität
3. Wartbarkeit: Server können einzeln aktualisiert werden
4. Lastverteilung: Kein Server wird überlastet

Was macht ein Load-Balancer genau?

Ein Load-Balancer ist ein Reverse-Proxy, der zwischen Clients und Servern sitzt und Anfragen intelligent verteilt.

Funktionsweise im Detail:

1. Client sendet Anfrage an Load-Balancer
   GET https://short.ly/abc123

2. Load-Balancer analysiert Anfrage
   - Welche Server sind verfügbar?
   - Welcher Server hat am wenigsten Last?
   - Welcher Algorithmus soll verwendet werden?

3. Load-Balancer wählt Server aus
   → API-Server-2 (geringste Last)

4. Load-Balancer leitet Anfrage weiter
   GET http://api-2:5000/abc123

5. Server verarbeitet Anfrage
   → Redis-Check → Redirect

6. Antwort geht zurück durch Load-Balancer
   HTTP 301 → Client

Load-Balancing-Algorithmen

1. Round-Robin (Standard)

Wie es funktioniert:

• Anfragen werden sequenziell an Server verteilt
• Server 1 → Server 2 → Server 3 → Server 1 → …

Beispiel:

Anfrage 1 → Server 1
Anfrage 2 → Server 2
Anfrage 3 → Server 3
Anfrage 4 → Server 1
Anfrage 5 → Server 2

Vorteile:

• Einfach zu implementieren
• Gleichmäßige Verteilung bei ähnlicher Server-Performance

Nachteile:

• Ignoriert aktuelle Server-Last
• Ignoriert Server-Kapazität (starker vs. schwacher Server)

2. Least Connections

Wie es funktioniert:

• Sendet Anfrage an Server mit den wenigsten aktiven Verbindungen

Beispiel:

Server 1: 100 aktive Verbindungen
Server 2: 50 aktive Verbindungen  ← Wird gewählt
Server 3: 75 aktive Verbindungen

Vorteile:

• Berücksichtigt aktuelle Server-Last
• Gut für langlebige Verbindungen (WebSockets, Streaming)

3. Weighted Round-Robin

Wie es funktioniert:

• Jeder Server hat ein Gewicht (z.B. Server 1 = 3, Server 2 = 1)
• Stärkere Server bekommen mehr Anfragen

Beispiel:

Server 1 (Gewicht 3): 3 Anfragen
Server 2 (Gewicht 1): 1 Anfrage
Server 1: 3 Anfragen
Server 2: 1 Anfrage

Vorteile:

• Berücksichtigt unterschiedliche Server-Kapazitäten
• Optimal wenn Server unterschiedlich stark sind

4. IP Hash (Sticky Sessions)

Wie es funktioniert:

• Hash der Client-IP bestimmt, welcher Server verwendet wird
• Gleiche IP → immer gleicher Server

Beispiel:

Client 192.168.1.1 → Hash → Server 2 (immer)
Client 192.168.1.2 → Hash → Server 1 (immer)

Vorteile:

• Session-Persistenz (wichtig für Stateful-Anwendungen)
• Cache-Freundlich (gleicher Client → gleicher Server)

Nachteile:

• Ungleichmäßige Verteilung bei wenigen Clients
• Problem wenn Server ausfällt (Sessions gehen verloren)

Health Checks: Warum sind sie kritisch?

Das Problem ohne Health Checks:

Server 2 ist abgestürzt, aber Load-Balancer weiß es nicht
→ Anfragen werden weiterhin an Server 2 gesendet
→ Client erhält Fehler (Timeout, 500 Error)
→ 33% der Anfragen schlagen fehl

Die Lösung: Health Checks

Ein Load-Balancer überprüft regelmäßig, ob Server erreichbar sind:

# Traefik Health Check Konfiguration
healthcheck:
  path: /health
  interval: 10s      # Alle 10 Sekunden prüfen
  timeout: 3s       # Timeout nach 3 Sekunden
  retries: 3        # 3 Fehlversuche = Server als "down" markieren

Health Check Endpoint im API-Server (Meta-Code Beispiel):

# Meta-Code: Vereinfachtes Beispiel zur Veranschaulichung
# In Produktion: Timeouts, detaillierte Checks, Metriken etc.

@app.route('/health', methods=['GET'])
def health_check():
    # Prüfe kritische Komponenten
    try:
        # 1. Redis erreichbar?
        redis.ping()
        
        # 2. Datenbank erreichbar?
        db.ping()  # Oder einfache Query
        
        # 3. Optional: Weitere Checks
        # - Disk Space
        # - Memory Usage
        # - External Services
        
        return {'status': 'healthy'}, 200
    except Exception as e:
        # Fehler: Server als "unhealthy" markieren
        return {'status': 'unhealthy', 'error': str(e)}, 503

Health Check Workflow:

1. Load-Balancer sendet GET /health an Server
2. Server prüft: Redis OK? Datenbank OK?
3. Server antwortet: 200 OK oder 503 Unhealthy
4. Load-Balancer markiert Server als "up" oder "down"
5. Nur "up" Server erhalten Anfragen

Vorteile:

• Automatisches Failover: Abgestürzte Server werden automatisch ausgeschlossen
• Selbstheilung: Wenn Server wieder online ist, wird er automatisch wieder eingebunden
• Keine manuelle Intervention: System läuft weiter ohne Administrator

Session-Persistenz (Sticky Sessions)

Das Problem:

Bei Stateful-Anwendungen (z.B. Shopping-Cart):

Request 1: Client → Load-Balancer → Server 1 (Cart wird erstellt)
Request 2: Client → Load-Balancer → Server 2 (Cart ist leer! Problem!)

Die Lösung: Sticky Sessions

# Traefik Cookie-basierte Session-Persistenz
labels:
  - "traefik.http.services.api.loadbalancer.sticky.cookie=true"
  - "traefik.http.services.api.loadbalancer.sticky.cookie.name=server_id"

Wie es funktioniert:

1. Erste Anfrage → Load-Balancer wählt Server 1
2. Load-Balancer setzt Cookie: server_id=server1
3. Weitere Anfragen → Cookie wird gelesen → Immer Server 1

Für unser URL-Shortener:

• Nicht notwendig: Unsere API ist stateless (kein Session-State)
• Aber nützlich: Kann Cache-Hit-Rate verbessern (gleicher Client → gleicher Server)

SSL/TLS Termination

Was ist SSL/TLS Termination?

Der Load-Balancer übernimmt die SSL-Entschlüsselung:

Client → [HTTPS verschlüsselt] → Load-Balancer → [HTTP unverschlüsselt] → API-Server

Vorteile:

• Performance: CPU-intensive SSL-Entschlüsselung nur im Load-Balancer
• Zentrales Zertifikats-Management: Nur Load-Balancer braucht Zertifikate
• Einfacheres Backend: API-Server müssen kein SSL handhaben

Traefik SSL-Konfiguration:

traefik:
  command:
    - "--certificatesresolvers.letsencrypt.acme.email=admin@short.ly"
    - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
    - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
  volumes:
    - ./letsencrypt:/letsencrypt

Rate Limiting und DDoS-Schutz

Das Problem: DDoS-Angriffe

Angreifer sendet 100.000 Anfragen/Sekunde
→ Ohne Rate Limiting: Alle Server überlastet
→ System bricht zusammen

Die Lösung: Rate Limiting im Load-Balancer

# Traefik Rate Limiting
labels:
  - "traefik.http.middlewares.ratelimit.ratelimit.average=100"
  - "traefik.http.middlewares.ratelimit.ratelimit.period=1s"
  - "traefik.http.routers.api.middlewares=ratelimit"

Wie es funktioniert:

• Maximal 100 Anfragen pro Sekunde pro Client
• Überschreitungen werden abgelehnt (429 Too Many Requests)
• Schützt Backend-Server vor Überlastung

Traefik-Konfiguration: Vollständiges Beispiel

docker-compose.yml für Traefik:

version: '3.8'

services:
  traefik:
    image: traefik:v2.10
    command:
      # API Dashboard (nur für Entwicklung)
      - "--api.insecure=true"
      
      # Docker Provider (automatische Service-Erkennung)
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      
      # Entry Points (Ports)
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      
      # SSL/TLS (Let's Encrypt)
      - "--certificatesresolvers.letsencrypt.acme.email=admin@short.ly"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
      
      # Logging
      - "--accesslog=true"
      - "--log.level=INFO"
    ports:
      - "80:80"      # HTTP
      - "443:443"    # HTTPS
      - "8080:8080"  # Traefik Dashboard
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./letsencrypt:/letsencrypt
    networks:
      - app-network

  api-1:
    build: ./api
    labels:
      # Traefik aktivieren
      - "traefik.enable=true"
      
      # Routing-Regeln
      - "traefik.http.routers.api.rule=Host(`short.ly`)"
      - "traefik.http.routers.api.entrypoints=web,websecure"
      - "traefik.http.routers.api.tls.certresolver=letsencrypt"
      
      # Service-Konfiguration
      - "traefik.http.services.api.loadbalancer.server.port=5000"
      
      # Load-Balancing-Algorithmus (Round-Robin ist Standard)
      # Für Least Connections:
      # - "traefik.http.services.api.loadbalancer.server.weight=1"
      
      # Health Checks
      - "traefik.http.services.api.loadbalancer.healthcheck.path=/health"
      - "traefik.http.services.api.loadbalancer.healthcheck.interval=10s"
      
      # Rate Limiting (optional)
      - "traefik.http.middlewares.ratelimit.ratelimit.average=100"
      - "traefik.http.routers.api.middlewares=ratelimit"
    networks:
      - app-network
    environment:
      - REDIS_HOST=redis
      - DB_HOST=postgres
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
      interval: 10s
      timeout: 3s
      retries: 3

  api-2:
    build: ./api
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.api.rule=Host(`short.ly`)"
      - "traefik.http.routers.api.entrypoints=web,websecure"
      - "traefik.http.routers.api.tls.certresolver=letsencrypt"
      - "traefik.http.services.api.loadbalancer.server.port=5000"
      - "traefik.http.services.api.loadbalancer.healthcheck.path=/health"
      - "traefik.http.services.api.loadbalancer.healthcheck.interval=10s"
    networks:
      - app-network
    environment:
      - REDIS_HOST=redis
      - DB_HOST=postgres
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
      interval: 10s
      timeout: 3s
      retries: 3

  api-3:
    build: ./api
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.api.rule=Host(`short.ly`)"
      - "traefik.http.routers.api.entrypoints=web,websecure"
      - "traefik.http.routers.api.tls.certresolver=letsencrypt"
      - "traefik.http.services.api.loadbalancer.server.port=5000"
      - "traefik.http.services.api.loadbalancer.healthcheck.path=/health"
      - "traefik.http.services.api.loadbalancer.healthcheck.interval=10s"
    networks:
      - app-network
    environment:
      - REDIS_HOST=redis
      - DB_HOST=postgres
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
      interval: 10s
      timeout: 3s
      retries: 3

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data
    networks:
      - app-network
    command: redis-server --maxmemory 2gb --maxmemory-policy allkeys-lru

  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=urlshortener
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - app-network

volumes:
  redis-data:
  postgres-data:

networks:
  app-network:
    driver: bridge

Monitoring und Metriken

Wichtige Load-Balancer-Metriken:

1. Request-Rate: Anfragen pro Sekunde
2. Response-Time: Durchschnittliche Antwortzeit
3. Error-Rate: Prozent der fehlgeschlagenen Anfragen
4. Server-Status: Welche Server sind “up” oder “down”?
5. Lastverteilung: Wie viele Anfragen pro Server?

Traefik Dashboard:

Zugriff auf http://localhost:8080 zeigt:

• Alle konfigurierten Routen
• Status aller Backend-Server
• Request-Metriken in Echtzeit
• Health-Check-Status

6. Skalierbarkeit: Warum horizontale Skalierung?

Das Problem: Vertikale vs. Horizontale Skalierung

Vertikale Skalierung (Scale-Up):

Ein Server: 4 Cores, 8GB RAM
     ↓
Größerer Server: 8 Cores, 16GB RAM
     ↓
Noch größerer Server: 16 Cores, 32GB RAM

Probleme:

1. Teuer: Größere Server kosten exponentiell mehr
2. Limits: Irgendwann gibt es keine größeren Server mehr
3. Downtime: Server muss offline für Hardware-Upgrade
4. Single Point of Failure: Ein Server = ein Ausfallpunkt

Horizontale Skalierung (Scale-Out):

1 Server: 4 Cores, 8GB RAM
     ↓
3 Server: 12 Cores, 24GB RAM (gesamt)
     ↓
10 Server: 40 Cores, 80GB RAM (gesamt)

Vorteile:

1. Kosteneffizient: Mehr kleine Server sind günstiger als ein großer
2. Praktisch unbegrenzt: Kann beliebig viele Server hinzufügen
3. Kein Downtime: Neue Server können live hinzugefügt werden
4. Hochverfügbarkeit: Wenn ein Server ausfällt, übernehmen andere

Warum horizontale Skalierung für unseren URL-Shortener?

Szenario: Wachstum der Anwendung

Start: 100 Anfragen/Sekunde → 1 Server reicht
     ↓
Nach 6 Monaten: 1.000 Anfragen/Sekunde → 3 Server nötig
     ↓
Nach 1 Jahr: 10.000 Anfragen/Sekunde → 10 Server nötig
     ↓
Nach 2 Jahren: 100.000 Anfragen/Sekunde → 50 Server nötig

Mit vertikaler Skalierung:

• Müssten Sie Server ständig ersetzen (teuer, Downtime)
• Irgendwann gibt es keine größeren Server mehr

Mit horizontaler Skalierung:

• Einfach mehr Server hinzufügen (günstig, kein Downtime)
• Praktisch unbegrenzt skalierbar

Anforderungen für horizontale Skalierung

1. Stateless API-Server

Was bedeutet “stateless”?

Ein stateless Server speichert keinen lokalen State (keine Session-Daten, kein lokaler Cache).

Stateless (gut für Skalierung):

# Jede Anfrage ist unabhängig
@app.route('/<short_code>')
def redirect(short_code):
    # Keine lokalen Variablen, keine Session-Daten
    url = get_url_from_redis_or_db(short_code)  # Externe Datenquelle
    return redirect(url)

Stateful (schlecht für Skalierung):

# Server speichert State lokal
session_data = {}  # Lokaler Speicher

@app.route('/<short_code>')
def redirect(short_code):
    # Problem: Wenn Request an anderen Server geht, ist State weg!
    if short_code in session_data:  # Nur auf diesem Server!
        return redirect(session_data[short_code])

Warum ist Stateless wichtig?

Request 1: Client → Load-Balancer → Server 1 (State gespeichert)
Request 2: Client → Load-Balancer → Server 2 (State fehlt! Problem!)

Mit stateless:

• Jeder Server ist identisch
• Jede Anfrage kann an jeden Server gehen
• Keine Abhängigkeit zwischen Anfragen

2. Shared Database

Warum eine gemeinsame Datenbank?

Server 1 erstellt: short.ly/abc123 → https://example.com
Server 2 erstellt: short.ly/xyz789 → https://test.com
Server 3 muss beide URLs kennen können!

Ohne Shared Database (jeder Server eigene DB):

Server 1 DB: abc123 → example.com
Server 2 DB: xyz789 → test.com
Server 3 DB: (leer)

Problem: Server 3 kennt abc123 und xyz789 nicht!

Mit Shared Database:

Alle Server → Gemeinsame Datenbank
Server 1: Erstellt abc123 → Speichert in DB
Server 2: Erstellt xyz789 → Speichert in DB
Server 3: Kann beide URLs abrufen → Liest aus DB

3. Shared Cache (Redis)

Warum ein gemeinsamer Cache?

Server 1: Cache für abc123 → example.com
Server 2: Cache für xyz789 → test.com
Server 3: Kein Cache

Problem: Server 3 muss immer zur Datenbank (langsam)

Mit Shared Cache:

Alle Server → Gemeinsamer Redis
Server 1: Cache für abc123 → Speichert in Redis
Server 2: Cache für xyz789 → Speichert in Redis
Server 3: Kann beide aus Redis lesen (schnell!)

4. Load Balancer

Warum ein Load-Balancer?

Ohne Load-Balancer müssten Clients wissen, welcher Server verfügbar ist:

Client muss wählen:
- Soll ich zu Server 1, 2 oder 3 gehen?
- Welcher Server ist verfügbar?
- Wie verteile ich Last gleichmäßig?

Mit Load-Balancer:

Client → Load-Balancer (wählt automatisch Server) → Server

Skalierung in der Praxis

Schritt 1: Start mit einem Server

services:
  api:
    build: ./api
    # Ein Server, kann ~1.000 Anfragen/Sekunde verarbeiten

Schritt 2: Skalierung bei steigender Last

# Docker Compose Skalierung
docker-compose up -d --scale api=3

# Jetzt: 3 Server, können ~3.000 Anfragen/Sekunde verarbeiten

Schritt 3: Automatische Skalierung (Auto-Scaling)

Bei Cloud-Providern (AWS, Google Cloud, Azure):

# Kubernetes Auto-Scaling Beispiel
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: api-autoscaler
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: api
  minReplicas: 3
  maxReplicas: 50
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

Wie Auto-Scaling funktioniert:

CPU-Auslastung < 50% → Reduziere Server (z.B. 3 → 2)
CPU-Auslastung > 70% → Erhöhe Server (z.B. 3 → 5)
CPU-Auslastung > 90% → Erhöhe Server (z.B. 5 → 10)

Vorteile:

• Kosteneffizient: Nur so viele Server wie nötig
• Automatisch: Keine manuelle Intervention
• Reagiert auf Last: Skaliert bei Traffic-Spitzen hoch

Skalierungs-Limits und Bottlenecks

Wichtige Überlegung: Wo sind die Limits?

1. API-Server (horizontale Skalierung möglich)

1 Server → 3 Server → 10 Server → 50 Server → 100 Server
✅ Praktisch unbegrenzt skalierbar

2. Load-Balancer (kann selbst skaliert werden)

1 Load-Balancer → 2 Load-Balancer (Active-Passive)
✅ Kann auch skaliert werden

3. Redis (kann zu Cluster erweitert werden)

1 Redis → Redis-Cluster (3-6 Nodes)
✅ Kann skaliert werden (Sharding)

4. Datenbank (kritischer Bottleneck!)

1 Datenbank → Read-Replicas (für Reads)
            → Master (für Writes)
⚠️ Writes sind schwerer zu skalieren

Datenbank-Skalierung:

Read-Replicas für bessere Read-Performance:

Master DB (Writes) → Replica 1 (Reads)
                  → Replica 2 (Reads)
                  → Replica 3 (Reads)

API-Server können Reads auf Replicas verteilen

Sharding für sehr große Datenmengen:

Shard 1: URLs a-m (20% der Daten)
Shard 2: URLs n-z (30% der Daten)
Shard 3: URLs 0-9 (50% der Daten)

Jeder Shard auf separatem Server

Skalierungsschritte: Praktisches Beispiel

Phase 1: MVP (1-100 Anfragen/Sekunde)

# 1 API-Server
docker-compose up -d

Phase 2: Wachstum (100-1.000 Anfragen/Sekunde)

# 3 API-Server
docker-compose up -d --scale api=3

Phase 3: Skalierung (1.000-10.000 Anfragen/Sekunde)

# 10 API-Server
docker-compose up -d --scale api=10

# Redis-Cluster für bessere Cache-Performance
# Datenbank Read-Replicas für bessere DB-Performance

Phase 4: Enterprise (10.000+ Anfragen/Sekunde)

# 50+ API-Server
# Redis-Cluster mit 6 Nodes
# Datenbank mit Sharding
# CDN für statische Inhalte
# Multi-Region Deployment

Monitoring der Skalierung

Wichtige Metriken zum Überwachen:

1. Request-Rate: Anfragen pro Sekunde pro Server
2. Response-Time: Durchschnittliche Antwortzeit
3. CPU-Auslastung: Sollte < 70% sein für Puffer
4. Memory-Auslastung: Sollte < 80% sein
5. Error-Rate: Sollte < 1% sein
6. Cache-Hit-Rate: Sollte > 95% sein

Wann sollte skaliert werden?

CPU > 70% für > 5 Minuten → Skaliere hoch
Response-Time > 200ms → Skaliere hoch
Error-Rate > 1% → Skaliere hoch
Cache-Hit-Rate < 90% → Prüfe Redis-Konfiguration

7. Erweiterte Optimierungen

Datenbank-Optimierung:

-- Partitionierung für große Tabellen
CREATE TABLE url_mappings_2025 PARTITION OF url_mappings
FOR VALUES FROM ('2025-01-01') TO ('2026-01-01');

-- Read Replicas für bessere Lesepfad-Performance

Caching-Optimierung:

• Hot URLs: Häufig aufgerufene URLs länger cachen
• Bloom Filter: Schnelle Prüfung ob Short-Code existiert (vor DB-Query)

Monitoring:

• Redis Hit-Rate überwachen
• Datenbank-Query-Performance tracken
• API-Response-Zeiten messen
• Load Balancer-Metriken beobachten

Zusammenfassung

Dieses System-Design bietet:

✅ Skalierbarkeit: Horizontale Skalierung durch stateless API-Server
✅ Performance: Redis-Caching für schnelle Antwortzeiten
✅ Zuverlässigkeit: Load Balancing verteilt Last gleichmäßig
✅ Einfachheit: Klare Trennung der Komponenten

Mit dieser Architektur können Sie Millionen von Short-URLs verwalten und tausende von Anfragen pro Sekunde verarbeiten.

Was ist MedusaJS?

MedusaJS ist ein modulares E-Commerce-Framework, das aus einem Node.js-Server und einem Admin-Dashboard besteht. Es bietet dir die Möglichkeit, einen vollständig anpassbaren Online-Shop zu erstellen, ohne dabei auf die Flexibilität verzichten zu müssen. Das Framework ist headless, was bedeutet, dass du dein eigenes Storefront mit deiner bevorzugten Technologie erstellen kannst.

Voraussetzungen

Bevor wir mit der Installation beginnen, stelle sicher, dass du folgende Tools auf deinem System installiert hast:

• Node.js v20+ (LTS Version) - Download
• Git CLI - Download
• PostgreSQL - Download

PostgreSQL Installation prüfen

Um zu überprüfen, ob PostgreSQL installiert ist, führe folgenden Befehl aus:

psql --version

Falls PostgreSQL noch nicht installiert ist, installiere es für dein Betriebssystem. Auf Ubuntu/Debian kannst du es mit folgendem Befehl installieren:

sudo apt-get update
sudo apt-get install postgresql postgresql-contrib

Installation: Der schnelle Weg

Die einfachste Methode, eine Medusa-Anwendung zu erstellen, ist die Verwendung des offiziellen create-medusa-app Tools. Dieses Tool richtet automatisch alles für dich ein, inklusive der Datenbankverbindung.

Schritt 1: Medusa-Anwendung erstellen

Öffne dein Terminal und führe folgenden Befehl aus:

npx create-medusa-app@latest my-medusa-store

Ersetze my-medusa-store mit dem Namen deines Projekts. Der Installer wird dich nach einigen Informationen fragen:

1. Projektname: Der Name deines Projekts (wird auch als Datenbankname verwendet)
2. Next.js Starter Storefront: Möchtest du das vorkonfigurierte Next.js Storefront installieren? (Ja/Nein)

Für den Anfang empfehle ich, mit “Nein” zu beginnen, damit du die Grundlagen der Medusa-Installation verstehst. Du kannst das Storefront später jederzeit hinzufügen.

Schritt 2: Installation abwarten

Der Installationsprozess kann einige Minuten dauern. Das Tool wird:

• Die Medusa-Anwendung in einem Verzeichnis mit deinem Projektnamen installieren
• Eine PostgreSQL-Datenbank für das Projekt einrichten
• Alle notwendigen Abhängigkeiten installieren
• Die Datenbank migrieren

Schritt 3: Erfolgreiche Installation

Nach erfolgreicher Installation sollte:

• Die Medusa-Anwendung auf http://localhost:9000 laufen
• Das Medusa Admin Dashboard auf http://localhost:9000/app verfügbar sein
• Der Installer automatisch das Admin Dashboard in deinem Browser öffnen

Schritt 4: Admin-User initialisieren

Nach dem Setup musst du den Admin-User initialisieren. Dies kannst du entweder über die Web-Oberfläche machen (beim ersten Öffnen des Admin Dashboards) oder über die Kommandozeile.

Option 1: Über die Web-Oberfläche

Beim ersten Öffnen des Admin Dashboards wirst du aufgefordert, einen Admin-Benutzer zu erstellen. Gib die Anmeldedaten ein und klicke auf “Erstellen”.

Option 2: Über die Kommandozeile (manuell)

Alternativ kannst du den Admin-User auch direkt über die Kommandozeile erstellen. Navigiere dazu in das Projektverzeichnis und führe folgenden Befehl aus:

cd my-medusa-store
npx medusa user -e user@email.de -p SuperSecretPassword

Ersetze:

• user@email.de mit deiner gewünschten E-Mail-Adresse
• SuperSecretPassword mit deinem gewünschten Passwort

Wichtig: Der Medusa-Server muss laufen, damit dieser Befehl funktioniert. Stelle sicher, dass der Entwicklungsserver gestartet ist.

Nach erfolgreicher Erstellung des Admin-Users kannst du dich im Admin Dashboard unter http://localhost:9000/app anmelden.

Entwicklungsserver starten

Um den Entwicklungsserver nach der Installation zu starten, navigiere in das Projektverzeichnis und führe folgenden Befehl aus:

cd my-medusa-store
npm run dev

Oder wenn du Yarn verwendest:

yarn dev

Der Server startet auf http://localhost:9000 und das Admin Dashboard ist unter http://localhost:9000/app erreichbar.

Projektstruktur verstehen

Nach der Installation solltest du folgende Verzeichnisstruktur sehen:

my-medusa-store/
├── src/
│   ├── api/          # API-Routen
│   ├── models/       # Datenbankmodelle
│   ├── services/     # Business-Logik
│   └── subscribers/  # Event-Subscriber
├── medusa-config.ts  # Hauptkonfigurationsdatei
├── package.json
└── .env              # Umgebungsvariablen

Wichtige Dateien

• medusa-config.ts: Die Hauptkonfigurationsdatei für deine Medusa-Anwendung
• .env: Enthält sensible Daten wie Datenbankverbindungen und API-Keys
• src/api/: Hier definierst du deine benutzerdefinierten API-Endpunkte

Konfiguration anpassen

CORS-Einstellungen

Wenn du später ein eigenes Storefront entwickelst, musst du die CORS-Einstellungen in der .env Datei anpassen:

STORE_CORS=http://localhost:3000
AUTH_CORS=http://localhost:5173,http://localhost:9000,http://localhost:3000

Füge die URLs deines Storefronts zu STORE_CORS hinzu, damit die Medusa API Anfragen von deinem Storefront akzeptiert.

Datenbankverbindung

Die Datenbankverbindung wird automatisch während der Installation konfiguriert. Du findest die Verbindungsdetails in der .env Datei:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/my-medusa-store

Alternative: Installation mit Docker

Falls du Docker bevorzugst oder Probleme mit der lokalen PostgreSQL-Installation hast, kannst du Medusa auch mit Docker einrichten.

Voraussetzungen für Docker

• Docker
• Docker Compose

Schritt 1: Repository klonen

git clone https://github.com/medusajs/medusa-starter-default.git --depth=1 my-medusa-store
cd my-medusa-store

Schritt 2: Docker Compose erstellen

Erstelle eine docker-compose.yml Datei:

services:
  postgres:
    image: postgres:15-alpine
    container_name: medusa_postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: medusa-store
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - medusa_network

volumes:
  postgres_data:

networks:
  medusa_network:

Schritt 3: Dependencies installieren

npm install --legacy-peer-deps

Schritt 4: Docker Container starten

docker compose up -d

Schritt 5: Medusa-Konfiguration anpassen

In medusa-config.ts musst du die SSL-Einstellungen für die Datenbankverbindung anpassen:

import { loadEnv, defineConfig } from "@medusajs/framework/utils"

loadEnv(process.env.NODE_ENV || "development", process.cwd())

module.exports = defineConfig({
  projectConfig: {
    // ... andere Konfigurationen
    databaseDriverOptions: {
      ssl: false,
      sslmode: "disable",
    },
  },
})

Schritt 6: Admin-User initialisieren

Nach dem Setup musst du den Admin-User manuell initialisieren. Dies ist notwendig, damit du dich im Admin Dashboard anmelden kannst.

Führe folgenden Befehl aus, um einen Admin-User zu erstellen:

docker compose exec medusa npx medusa user -e user@email.de -p SuperSecretPassword

Ersetze:

• user@email.de mit deiner gewünschten E-Mail-Adresse
• SuperSecretPassword mit deinem gewünschten Passwort

Wichtig: Der Medusa-Container muss laufen, damit dieser Befehl funktioniert. Stelle sicher, dass alle Container gestartet sind (docker compose up -d).

Nach erfolgreicher Erstellung des Admin-Users kannst du dich im Admin Dashboard unter http://localhost:9000/app anmelden.

Erste Schritte im Admin Dashboard

Nachdem du dich im Admin Dashboard angemeldet hast, kannst du:

1. Produkte erstellen: Navigiere zu “Products” und füge dein erstes Produkt hinzu
2. Regionen konfigurieren: Richte Versandregionen und Steuersätze ein
3. Zahlungsmethoden einrichten: Konfiguriere Zahlungsanbieter wie Stripe
4. Versandoptionen: Definiere Versandmethoden für deine Regionen

Häufige Probleme und Lösungen

Problem: Installation schlägt fehl

Lösung: Stelle sicher, dass:

• Node.js v20 oder höher installiert ist
• PostgreSQL läuft und erreichbar ist
• Genügend Festplattenspeicher verfügbar ist

Problem: CORS-Fehler

Lösung: Überprüfe die CORS-Einstellungen in deiner .env Datei und füge die URL deines Storefronts hinzu.

Problem: Datenbankverbindungsfehler

Lösung:

• Überprüfe, ob PostgreSQL läuft: sudo systemctl status postgresql
• Überprüfe die DATABASE_URL in der .env Datei
• Stelle sicher, dass die Datenbank existiert

Problem: Port bereits belegt

Lösung: Ändere den Port in der medusa-config.ts oder beende den Prozess, der den Port verwendet.

Nächste Schritte

Nach erfolgreicher Installation kannst du:

1. Storefront entwickeln: Erstelle dein eigenes Storefront mit Next.js, React oder einer anderen Technologie
2. Plugins installieren: Erweitere Medusa mit offiziellen oder Community-Plugins
3. API anpassen: Passe die API-Endpunkte an deine Bedürfnisse an
4. Custom Services: Erstelle eigene Services für spezielle Business-Logik

Fazit

MedusaJS bietet eine solide Grundlage für dein E-Commerce-Projekt. Mit diesem Setup hast du eine vollständig funktionsfähige Backend-Infrastruktur, die du nach deinen Wünschen anpassen kannst. Die modulare Architektur ermöglicht es dir, genau die Features zu implementieren, die du benötigst, ohne unnötigen Ballast.

Falls du Fragen hast oder auf Probleme stößt, schaue in die offizielle Medusa-Dokumentation oder die Troubleshooting-Guides.

Viel Erfolg mit deinem MedusaJS-Projekt! 🚀

Warum Stripe mit MedusaJS?

Stripe bietet eine robuste, sichere und benutzerfreundliche Lösung für die Zahlungsabwicklung. Die Integration mit MedusaJS ermöglicht es dir:

• Kreditkartenzahlungen zu akzeptieren
• Alternative Zahlungsmethoden wie Bancontact, iDEAL, giropay und mehr anzubieten
• Automatische Zahlungsabwicklung mit Webhooks
• Gespeicherte Zahlungsmethoden für wiederkehrende Kunden zu unterstützen
• Apple Pay und Google Pay zu integrieren

Voraussetzungen

Bevor wir mit der Integration beginnen, stelle sicher, dass du:

1. Eine funktionierende MedusaJS-Anwendung hast (siehe MedusaJS Setup Tutorial)
2. Ein Stripe-Konto besitzt - Registrierung
3. Zugriff auf deine Stripe API Keys hast

Stripe API Keys abrufen

1. Logge dich in dein Stripe Dashboard ein
2. Navigiere zu Developers > API keys
3. Du findest dort:
   • Publishable key (beginnt mit pk_test_ oder pk_live_)
   • Secret key (beginnt mit sk_test_ oder sk_live_)

Wichtig: Für die Entwicklung verwende die Test Keys (mit _test_). Für Production benötigst du die Live Keys (mit _live_).

Schritt 1: Stripe Module Provider registrieren

Der Stripe Module Provider ist standardmäßig in deiner Medusa-Anwendung installiert. Um ihn zu aktivieren, musst du ihn in der Konfigurationsdatei registrieren.

medusa-config.ts anpassen

Öffne die medusa-config.ts Datei in deinem Medusa-Projekt und füge den Stripe Module Provider hinzu:

module.exports = defineConfig({
  // ... andere Konfigurationen
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "@medusajs/medusa/payment-stripe",
            id: "stripe",
            options: {
              apiKey: process.env.STRIPE_API_KEY,
            },
          },
        ],
      },
    },
  ],
})

Wichtig: Auch wenn das Payment Module standardmäßig geladen wird, musst du es erneut in der modules-Array hinzufügen, wenn du einen neuen Provider registrierst.

Erweiterte Konfigurationsoptionen

Der Stripe Module Provider unterstützt weitere Optionen:

{
  resolve: "@medusajs/medusa/payment-stripe",
  id: "stripe",
  options: {
    apiKey: process.env.STRIPE_API_KEY,
    webhookSecret: process.env.STRIPE_WEBHOOK_SECRET, // Für Production
    automaticPaymentMethods: true, // Für Apple Pay, Google Pay
    capture: true, // Automatische Zahlungserfassung
    paymentDescription: "Bestellung bei meinem Shop", // Standard-Beschreibung
  },
}

Optionen im Detail:

• apiKey (erforderlich): Dein Stripe Secret API Key
• webhookSecret (optional, für Production): Webhook Secret für sichere Webhook-Verarbeitung
• automaticPaymentMethods (optional): Aktiviert automatische Zahlungsmethoden wie Apple Pay und Google Pay
• capture (optional): Ob Zahlungen automatisch erfasst werden sollen (Standard: false)
• paymentDescription (optional): Standard-Beschreibung für Zahlungen

Schritt 2: Environment Variables setzen

Füge deine Stripe API Keys zur .env Datei hinzu:

STRIPE_API_KEY=sk_test_51J...

Für Production füge auch das Webhook Secret hinzu:

STRIPE_API_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

Sicherheitshinweis: Stelle sicher, dass deine .env Datei in .gitignore enthalten ist und niemals in dein Repository committed wird!

Schritt 3: Stripe in einer Region aktivieren

Nach der Konfiguration musst du Stripe als Zahlungsanbieter in mindestens einer Region aktivieren. Kunden können nur Zahlungsmethoden verwenden, die in ihrer Region verfügbar sind.

Über das Admin Dashboard

1. Starte deine Medusa-Anwendung:

npm run dev

1. Öffne das Admin Dashboard unter http://localhost:9000/app
2. Logge dich mit deinem Admin-Account ein
3. Navigiere zu Settings > Regions
4. Klicke auf die Region, in der du Stripe aktivieren möchtest
5. Klicke auf das Bearbeiten-Icon (oben rechts im ersten Abschnitt)
6. Im sich öffnenden Seitenfenster findest du das Feld “Payment Providers”
7. Wähle “Stripe (STRIPE)” aus dem Dropdown-Menü
8. Klicke auf “Save”

Stripe ist jetzt als Zahlungsoption im Checkout verfügbar!

Schritt 4: Verfügbare Stripe-Zahlungsmethoden

Der Stripe Module Provider registriert verschiedene Zahlungsanbieter. Jeder Provider hat eine eindeutige ID im Format {provider_id}_{module_id}.

Wenn du die Stripe Module Provider ID auf "stripe" gesetzt hast, werden folgende Provider registriert:

Du kannst jeden dieser Provider separat in deinen Regionen aktivieren, je nachdem, welche Zahlungsmethoden du anbieten möchtest.

Schritt 5: Webhooks für Production konfigurieren

Für Production-Anwendungen ist es essentiell, Stripe Webhooks einzurichten. Webhooks informieren deine Medusa-Anwendung über Änderungen und Updates zu Zahlungen, die asynchron verarbeitet werden.

Warum Webhooks wichtig sind

Webhooks sind wichtig, wenn:

• Zahlungen asynchron verarbeitet werden
• Zahlungen auf der Stripe-Seite verwaltet werden
• Der Checkout-Prozess unterbrochen wurde und die Zahlung trotzdem verarbeitet wurde

Webhook URL

Die Webhook-URL für MedusaJS folgt diesem Format:

https://deine-domain.com/hooks/payment/{provider_id}/stripe

Für die Standard-Stripe-Zahlung wäre die URL:

https://deine-domain.com/hooks/payment/stripe_stripe/stripe

Für verschiedene Zahlungsmethoden:

Webhook in Stripe einrichten

1. Gehe zu deinem Stripe Dashboard
2. Navigiere zu Developers > Webhooks
3. Klicke auf “Add endpoint”
4. Gib deine Webhook-URL ein (z.B. https://deine-domain.com/hooks/payment/stripe_stripe/stripe)
5. Wähle die folgenden Events aus:
   • payment_intent.succeeded
   • payment_intent.payment_failed
   • charge.succeeded
   • charge.failed (seit Medusa v2.8.5)
6. Klicke auf “Add endpoint”
7. Kopiere das Webhook Secret (beginnt mit whsec_)
8. Füge es zu deiner .env Datei hinzu:

STRIPE_WEBHOOK_SECRET=whsec_...

1. Aktualisiere deine medusa-config.ts:

{
  resolve: "@medusajs/medusa/payment-stripe",
  id: "stripe",
  options: {
    apiKey: process.env.STRIPE_API_KEY,
    webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
  },
}

Webhook lokal testen

Für lokale Tests kannst du Stripe CLI verwenden:

# Stripe CLI installieren
# Dann Webhook weiterleiten
stripe listen --forward-to localhost:9000/hooks/payment/stripe_stripe/stripe

Die CLI zeigt dir ein Webhook Secret an, das du für lokale Tests verwenden kannst.

Schritt 6: Storefront-Integration

Wenn du ein eigenes Storefront entwickelst (z.B. mit Next.js), benötigst du auch den Stripe Publishable Key.

Environment Variable im Storefront

Füge den Publishable Key zu deinen Storefront-Umgebungsvariablen hinzu:

# Next.js Storefront
NEXT_PUBLIC_STRIPE_KEY=pk_test_...

# Oder für andere Frameworks
STRIPE_PUBLISHABLE_KEY=pk_test_...

Wichtig: Der Publishable Key kann sicher im Frontend verwendet werden, da er nur für die Initialisierung von Stripe-Elementen verwendet wird.

Erweiterte Features

Gespeicherte Zahlungsmethoden

Der Stripe Module Provider unterstützt gespeicherte Zahlungsmethoden. Kunden können ihre Zahlungsinformationen speichern und bei zukünftigen Bestellungen wiederverwenden.

Die Implementierung erfordert zusätzliche Anpassungen im Storefront. Weitere Details findest du in der offiziellen Medusa-Dokumentation.

Apple Pay und Google Pay

Um Apple Pay und Google Pay zu aktivieren:

1. Setze automaticPaymentMethods: true in der Stripe-Konfiguration
2. Implementiere die entsprechenden UI-Elemente in deinem Storefront
3. Stelle sicher, dass deine Domain für Apple Pay verifiziert ist

Zahlungsbeschreibungen anpassen

Du kannst benutzerdefinierte Beschreibungen für Zahlungen festlegen:

// In medusa-config.ts
{
  options: {
    paymentDescription: "Bestellung #{order_number} bei meinem Shop",
  },
}

Oder dynamisch im Cart Context:

// Im Storefront
const cart = await medusa.carts.create({
  // ... andere Optionen
  context: {
    payment_description: "Spezielle Bestellung",
  },
})

Häufige Probleme und Lösungen

Problem: Stripe erscheint nicht in den Payment Providers

Lösung:

• Überprüfe, ob der Stripe Module Provider korrekt in medusa-config.ts registriert ist
• Stelle sicher, dass STRIPE_API_KEY in der .env Datei gesetzt ist
• Starte den Medusa-Server neu

Problem: Zahlungen werden nicht verarbeitet

Lösung:

• Überprüfe, ob Stripe in der Region aktiviert ist
• Stelle sicher, dass du den richtigen API Key verwendest (Test vs. Live)
• Überprüfe die Stripe-Logs im Dashboard auf Fehler

Problem: Webhook-Events werden nicht empfangen

Lösung:

• Überprüfe, ob die Webhook-URL korrekt ist
• Stelle sicher, dass deine Anwendung öffentlich erreichbar ist (für Production)
• Überprüfe, ob das webhookSecret korrekt gesetzt ist
• Teste die Webhook-URL mit Stripe CLI lokal

Problem: CORS-Fehler im Storefront

Lösung:

• Füge deine Storefront-URL zu STORE_CORS in der .env Datei hinzu:

STORE_CORS=http://localhost:3000,https://deine-domain.com

Problem: SSL-Fehler bei Webhooks

Lösung:

• Stelle sicher, dass deine Production-URL HTTPS verwendet
• Überprüfe, ob dein SSL-Zertifikat gültig ist
• Für lokale Tests verwende Stripe CLI

Testen der Integration

Test-Kreditkarten

Stripe bietet Test-Kreditkarten für die Entwicklung:

• Erfolgreiche Zahlung: 4242 4242 4242 4242
• Abgelehnte Zahlung: 4000 0000 0000 0002
• 3D Secure erforderlich: 4000 0025 0000 3155

Weitere Test-Karten findest du in der Stripe-Dokumentation.

Zahlungsfluss testen

1. Erstelle ein Produkt im Admin Dashboard
2. Füge es zum Warenkorb hinzu
3. Gehe zum Checkout
4. Wähle Stripe als Zahlungsmethode
5. Verwende eine Test-Kreditkarte
6. Überprüfe im Stripe Dashboard, ob die Zahlung registriert wurde

Best Practices

1. Sicherheit:
   • Verwende niemals Live Keys in der Entwicklung
   • Speichere Secrets sicher (z.B. in Environment Variables)
   • Implementiere Rate Limiting für Webhook-Endpunkte
2. Error Handling:
   • Implementiere umfassendes Error Handling im Storefront
   • Zeige benutzerfreundliche Fehlermeldungen
   • Logge Fehler für Debugging
3. Monitoring:
   • Überwache Webhook-Events im Stripe Dashboard
   • Setze Alerts für fehlgeschlagene Zahlungen
   • Überprüfe regelmäßig die Medusa-Logs
4. Testing:
   • Teste alle Zahlungsmethoden vor dem Go-Live
   • Teste Webhook-Events mit Stripe CLI
   • Führe umfassende Integrationstests durch

Nächste Schritte

Nach erfolgreicher Stripe-Integration kannst du:

1. Weitere Zahlungsmethoden aktivieren: Bancontact, iDEAL, giropay, etc.
2. Gespeicherte Zahlungsmethoden implementieren: Für wiederkehrende Kunden
3. Subscriptions einrichten: Für wiederkehrende Zahlungen
4. Custom Payment Flows: Anpassen des Checkout-Prozesses
5. Analytics integrieren: Zahlungsstatistiken tracken

Fazit

Die Integration von Stripe in MedusaJS ist unkompliziert und bietet dir eine solide Grundlage für die Zahlungsabwicklung in deinem E-Commerce-Shop. Mit diesem Setup kannst du verschiedene Zahlungsmethoden anbieten und sicher Zahlungen verarbeiten.

Falls du Fragen hast oder auf Probleme stößt, schaue in die offizielle Medusa-Dokumentation oder die Stripe-Dokumentation.

Viel Erfolg mit deiner Stripe-Integration! 💳

Was ist Matrix?

Matrix ist ein offenes Protokoll für dezentrale, Echtzeit-Kommunikation. Die wichtigsten Vorteile:

• Dezentral: Jeder kann seinen eigenen Server betreiben
• Federiert: Server können miteinander kommunizieren (wie E-Mail)
• Ende-zu-Ende verschlüsselt: Sichere Kommunikation
• Open Source: Vollständig transparent und anpassbar
• Multi-Client: Verschiedene Clients für verschiedene Plattformen
• Rich Features: Text, Voice, Video, Dateien, etc.

Architektur-Übersicht

Dieses Setup umfasst folgende Komponenten:

1. Synapse: Der Matrix-Homeserver (Hauptkomponente)
2. PostgreSQL: Datenbank für Synapse
3. Element Web: Web-basierter Chat-Client
4. Traefik: Reverse-Proxy mit automatischem SSL
5. Coturn: TURN-Server für Voice/Video-Calls
6. LiveKit: Moderne WebRTC-Infrastruktur für Video-Calls
7. Synapse Admin: Web-Interface zur Server-Verwaltung
8. Mautrix WhatsApp (optional): Bridge zu WhatsApp

Voraussetzungen

Bevor wir mit der Installation beginnen, stelle sicher, dass du folgende Voraussetzungen erfüllst:

Systemanforderungen

• Docker Version 20.10 oder höher - Download
• Docker Compose Version 2.0 oder höher - Download
• Mindestens 2GB RAM (4GB+ empfohlen)
• Mindestens 10GB freier Speicherplatz
• Eine Domain mit DNS-Zugriff (für SSL-Zertifikate)

Installation prüfen

Überprüfe, ob Docker und Docker Compose installiert sind:

docker --version
docker compose version

DNS-Konfiguration

Du benötigst eine Domain mit folgenden DNS-Einträgen:

• matrix.deine-domain.de → Deine Server-IP (für Synapse)
• chat.deine-domain.de → Deine Server-IP (für Element)
• rtc.deine-domain.de → Deine Server-IP (für LiveKit, optional)
• jwt.deine-domain.de → Deine Server-IP (für JWT-Service, optional)

Wichtig: Stelle sicher, dass diese DNS-Einträge aktiv sind, bevor du mit dem Setup beginnst, da Let’s Encrypt die Domain-Validierung durchführt.

Schritt 1: Projekt-Verzeichnis erstellen

Erstelle ein neues Verzeichnis für dein Matrix-Setup:

mkdir matrix-server
cd matrix-server

Schritt 2: Umgebungsvariablen konfigurieren

Erstelle eine .env Datei mit allen notwendigen Konfigurationswerten:

nano .env

Füge folgende Variablen ein und passe sie an deine Umgebung an:

# Synapse Konfiguration
SYNAPSE_SERVER_NAME=matrix.deine-domain.de
SYNAPSE_REPORT_STATS=true

# PostgreSQL
POSTGRES_PASSWORD=dein_sicheres_datenbank_passwort

# AWS S3 für Media Storage (optional, aber empfohlen)
AWS_ACCESS_KEY_ID=dein_aws_access_key
AWS_SECRET_ACCESS_KEY=dein_aws_secret_key
AWS_DEFAULT_REGION=eu-central-1
AWS_S3_ADDRESSING_STYLE=path

# TURN Server Konfiguration
TURN_DOMAIN=rtc.deine-domain.de
TURN_REALM=rtc.deine-domain.de
TURN_STATIC_AUTH_SECRET=generiere_ein_langes_zufaelliges_secret
EXTERNAL_IP=deine_oeffentliche_ip_adresse
RELAY_IP=deine_oeffentliche_ip_adresse

# LiveKit Konfiguration
LIVEKIT_API_KEY=generiere_einen_api_key
LIVEKIT_API_SECRET=generiere_ein_langes_secret

# Mautrix WhatsApp Bridge (optional)
MW_POSTGRES_PASSWORD=dein_whatsapp_bridge_datenbank_passwort

Wichtige Konfigurationsoptionen im Detail

SYNAPSE_SERVER_NAME:

• Dies ist der Domain-Name deines Matrix-Servers
• Muss mit deiner DNS-Konfiguration übereinstimmen
• Beispiel: matrix.example.com

SYNAPSE_REPORT_STATS:

• true: Sende anonyme Statistiken an matrix.org
• false: Keine Statistiken senden

POSTGRES_PASSWORD:

• Starkes Passwort für die PostgreSQL-Datenbank
• Verwende einen Passwort-Generator für Production

TURN_STATIC_AUTH_SECRET:

• Generiere ein zufälliges Secret für TURN-Authentifizierung
• Mindestens 32 Zeichen lang
• Generieren mit: openssl rand -hex 32

LIVEKIT_API_KEY und LIVEKIT_API_SECRET:

• Für Video-Calls benötigt
• Generiere mit: openssl rand -hex 16 (für Key) und openssl rand -hex 32 (für Secret)

Sicherheitshinweis: Bewahre deine .env Datei sicher auf und teile sie niemals öffentlich!

Schritt 3: Verzeichnisstruktur erstellen

Erstelle die notwendigen Verzeichnisse für Konfigurationen und Daten:

mkdir -p synapse element/config.json traefik well-known/matrix/server whatsapp certs

Schritt 4: Traefik ACME-Datei erstellen

Erstelle die Datei für Let’s Encrypt-Zertifikate:

touch traefik/acme.json
chmod 600 traefik/acme.json

Die Berechtigung 600 ist wichtig, damit nur der Besitzer die Datei lesen/schreiben kann.

Schritt 5: Synapse-Konfiguration generieren

Synapse benötigt eine initiale Konfigurationsdatei. Wir generieren sie mit dem offiziellen Synapse-Image:

docker run -it --rm \
  -v $(pwd)/synapse:/data \
  -e SYNAPSE_SERVER_NAME=matrix.deine-domain.de \
  -e SYNAPSE_REPORT_STATS=true \
  matrixdotorg/synapse:latest generate

Wichtig: Ersetze matrix.deine-domain.de mit deinem tatsächlichen Domain-Namen!

Dies erstellt die Datei synapse/homeserver.yaml. Wir werden diese später anpassen.

Schritt 6: Synapse-Konfiguration anpassen

Öffne die generierte synapse/homeserver.yaml und passe folgende Einstellungen an:

nano synapse/homeserver.yaml

Wichtige Konfigurationen:

Datenbank-Verbindung (bereits konfiguriert durch Umgebungsvariablen):

database:
  name: psycopg2
  args:
    user: synapse
    password: ${POSTGRES_PASSWORD}
    database: synapse
    host: db
    cp_min: 5
    cp_max: 10

Media Storage (für S3, optional):

media_store_path: "/data/media_store"
s3:
  enabled: true
  bucket_name: "dein-s3-bucket-name"
  region_name: "eu-central-1"
  access_key_id: "${AWS_ACCESS_KEY_ID}"
  secret_access_key: "${AWS_SECRET_ACCESS_KEY}"
  addressing_style: "path"

TURN-Server Konfiguration:

turn_uris:
  - "turn:rtc.deine-domain.de:3478?transport=udp"
  - "turn:rtc.deine-domain.de:3478?transport=tcp"
  - "turns:rtc.deine-domain.de:5349?transport=udp"
  - "turns:rtc.deine-domain.de:5349?transport=tcp"

turn_shared_secret: "${TURN_STATIC_AUTH_SECRET}"
turn_user_lifetime: 86400000
turn_allow_guests: true

LiveKit Integration (für moderne Video-Calls):

livekit:
  url: "wss://rtc.deine-domain.de/livekit/sfu"
  api_key: "${LIVEKIT_API_KEY}"
  api_secret: "${LIVEKIT_API_SECRET}"

Federation (wichtig für Kommunikation mit anderen Servern):

federation_domain_whitelist: []
# Leer lassen = alle Domains erlauben
# Oder spezifische Domains auflisten

Registrierung (für neue Benutzer):

enable_registration: true
enable_registration_without_verification: false
registration_shared_secret: "generiere_ein_langes_secret_hier"

Schritt 7: Element-Konfiguration erstellen

Erstelle die Konfigurationsdatei für Element Web:

nano element/config.json

Füge folgende Konfiguration ein:

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.deine-domain.de",
      "server_name": "matrix.deine-domain.de"
    },
    "m.identity_server": {
      "base_url": "https://vector.im"
    }
  },
  "default_server_name": "matrix.deine-domain.de",
  "brand": "Dein Chat",
  "integrations_ui_url": "https://scalar.vector.im/",
  "integrations_rest_url": "https://scalar.vector.im/api",
  "integrations_widgets_urls": [
    "https://scalar.vector.im/_matrix/integrations/v1",
    "https://scalar.vector.im/_matrix/integrations/v2",
    "https://scalar-staging.vector.im/_matrix/integrations/v1",
    "https://scalar-staging.vector.im/_matrix/integrations/v2",
    "https://scalar-staging.riot.im/scalar/api"
  ],
  "bug_report_endpoint_url": "https://element.io/bugreports/submit",
  "defaultCountryCode": "DE",
  "showLabsSettings": true,
  "features": {
    "feature_new_spinner": true,
    "feature_pinning": true,
    "feature_custom_status": true,
    "feature_custom_tags": true,
    "feature_state_resolver": true,
    "feature_mjolnir": true,
    "feature_dnd": true,
    "feature_bridge_state": true,
    "feature_presence_in_room_list": true,
    "feature_cross_signing": true,
    "feature_new_device_manager": true,
    "feature_video_rooms": true,
    "feature_element_call": true,
    "feature_livekit": true
  },
  "default_federate": true,
  "default_theme": "light",
  "roomDirectory": {
    "servers": [
      "matrix.deine-domain.de",
      "matrix.org"
    ]
  },
  "settingDefaults": {
    "breadcrumbs": true
  },
  "jitsi": {
    "preferredDomain": "meet.jit.si"
  },
  "livekit": {
    "url": "wss://rtc.deine-domain.de/livekit/sfu",
    "jwt_service_url": "https://jwt.deine-domain.de"
  }
}

Wichtig: Ersetze alle deine-domain.de Einträge mit deiner tatsächlichen Domain!

Schritt 8: Well-Known Konfiguration

Erstelle die Well-Known-Dateien für Matrix-Discovery:

mkdir -p well-known/matrix

Erstelle well-known/matrix/server:

nano well-known/matrix/server

Füge folgendes ein (ersetze mit deiner Domain):

{
  "m.server": "matrix.deine-domain.de:443"
}

Erstelle well-known/matrix/client:

nano well-known/matrix/client

{
  "m.homeserver": {
    "base_url": "https://matrix.deine-domain.de"
  },
  "m.identity_server": {
    "base_url": "https://vector.im"
  }
}

Schritt 9: Docker Compose Datei erstellen

Erstelle die docker-compose.yml Datei:

nano docker-compose.yml

Füge die vollständige docker-compose.yml ein (siehe unten im Dokument).

Schritt 10: Container starten

Starte alle Container:

docker compose up -d

Der -d Flag startet die Container im Hintergrund. Du kannst den Status überprüfen mit:

docker compose ps

Die Container sollten jetzt starten. Der erste Start kann einige Minuten dauern, da:

• PostgreSQL die Datenbank initialisiert
• Synapse die Datenbank-Schema erstellt
• Traefik SSL-Zertifikate von Let’s Encrypt anfordert

Schritt 11: Logs überwachen

Überwache die Logs, um sicherzustellen, dass alles korrekt startet:

# Alle Container
docker compose logs -f

# Nur Synapse
docker compose logs -f synapse

# Nur Traefik (für SSL-Status)
docker compose logs -f traefik

Wichtige Log-Meldungen

Synapse:

• Server started, listening on port 8008 → Server läuft
• Database is ready → Datenbankverbindung erfolgreich
• Federation is ready → Federation aktiviert

Traefik:

• Certificate obtained from ACME → SSL-Zertifikat erfolgreich
• Server configuration reloaded → Konfiguration geladen

Schritt 12: Ersten Benutzer erstellen

Nachdem Synapse gestartet ist, erstelle den ersten Admin-Benutzer:

docker compose exec synapse register_new_matrix_user -c /data/homeserver.yaml -a -u admin -p dein_admin_passwort

Wichtig:

• -a macht den Benutzer zum Administrator
• Verwende ein starkes Passwort!
• Speichere die Credentials sicher!

Schritt 13: Auf den Server zugreifen

Nach erfolgreichem Start kannst du auf folgende URLs zugreifen:

• Element Web Client: https://chat.deine-domain.de
• Synapse API: https://matrix.deine-domain.de
• Synapse Admin: http://deine-server-ip:8081
• Traefik Dashboard: http://deine-server-ip:8080 (falls aktiviert)

Schritt 14: Erste Anmeldung

1. Öffne https://chat.deine-domain.de in deinem Browser
2. Klicke auf “Sign In”
3. Wähle “Edit” neben dem Server-Namen
4. Gib https://matrix.deine-domain.de ein
5. Melde dich mit deinem Admin-Account an

Erweiterte Konfiguration

Media Storage mit S3

Für Production-Umgebungen wird empfohlen, Media-Dateien in S3 zu speichern:

1. Erstelle einen S3-Bucket bei AWS (oder kompatiblem Service)
2. Konfiguriere die AWS-Credentials in der .env Datei
3. Aktiviere S3 in der homeserver.yaml (siehe Schritt 6)

WhatsApp-Bridge einrichten

Die Mautrix WhatsApp Bridge ermöglicht es, WhatsApp-Nachrichten über Matrix zu empfangen/senden:

1. Starte die Bridge: docker compose up -d mautrix-whatsapp
2. Öffne http://deine-server-ip:29318 im Browser
3. Folge der Anleitung zum QR-Code-Scan
4. Die Bridge wird automatisch als AppService in Synapse registriert

Backup-Strategie

Datenbank-Backup:

docker compose exec db pg_dump -U synapse synapse > backup_$(date +%Y%m%d).sql

Synapse-Daten-Backup:

tar -czf synapse_backup_$(date +%Y%m%d).tar.gz synapse/

Automatische Backups (mit Cron):

# Füge zu crontab hinzu (crontab -e)
0 2 * * * cd /pfad/zum/matrix-server && docker compose exec -T db pg_dump -U synapse synapse > backups/db_$(date +\%Y\%m\%d).sql

Häufige Probleme und Lösungen

Problem: SSL-Zertifikat wird nicht erstellt

Symptome: Traefik-Logs zeigen ACME-Fehler

Lösungen:

• Überprüfe, ob die DNS-Einträge korrekt sind: dig matrix.deine-domain.de
• Stelle sicher, dass Port 80 und 443 von außen erreichbar sind
• Überprüfe die Firewall-Einstellungen
• Warte einige Minuten, Let’s Encrypt hat Rate-Limits

Problem: Synapse startet nicht

Symptome: Container stoppt sofort oder Logs zeigen Fehler

Lösungen:

• Überprüfe die Logs: docker compose logs synapse
• Stelle sicher, dass PostgreSQL läuft: docker compose ps db
• Überprüfe die homeserver.yaml auf Syntax-Fehler
• Stelle sicher, dass die Datenbank-Credentials korrekt sind

Problem: Federation funktioniert nicht

Symptome: Kann nicht mit anderen Matrix-Servern kommunizieren

Lösungen:

• Überprüfe, ob Port 8448 von außen erreichbar ist
• Teste mit: https://federationtester.matrix.org/#matrix.deine-domain.de
• Stelle sicher, dass die Well-Known-Dateien korrekt sind
• Überprüfe die Traefik-Labels für Federation

Problem: TURN-Server funktioniert nicht

Symptome: Voice/Video-Calls funktionieren nicht

Lösungen:

• Überprüfe die TURN-Konfiguration in homeserver.yaml
• Stelle sicher, dass die Ports 3478 und 5349 geöffnet sind
• Überprüfe die TURN_STATIC_AUTH_SECRET in der .env
• Teste mit: https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/

Problem: Element lädt nicht

Symptome: Weißer Bildschirm oder Fehler beim Laden

Lösungen:

• Überprüfe die config.json auf Syntax-Fehler
• Stelle sicher, dass die Domain in der Konfiguration korrekt ist
• Überprüfe die Browser-Konsole auf Fehler
• Stelle sicher, dass Traefik die Route korrekt konfiguriert hat

Performance-Optimierung

Datenbank-Optimierung

Füge in homeserver.yaml hinzu:

database:
  args:
    cp_min: 5
    cp_max: 10
    cp_reconnect: true

Synapse-Optimierung

Für größere Installationen:

media_store_path: "/data/media_store"
max_upload_size: "50M"
max_image_pixels: "32M"

Ressourcen-Limits

Füge in docker-compose.yml Ressourcen-Limits hinzu:

synapse:
  deploy:
    resources:
      limits:
        cpus: '2'
        memory: 2G
      reservations:
        cpus: '1'
        memory: 1G

Sicherheits-Best-Practices

1. Firewall konfigurieren:
   • Öffne nur Ports 80, 443, 8448
   • Blockiere alle anderen Ports
2. Regelmäßige Updates:

   docker compose pull
   docker compose up -d
   

3. Starke Passwörter:
   • Verwende Passwort-Manager
   • Aktiviere 2FA für Admin-Accounts
4. Backups:
   • Tägliche Datenbank-Backups
   • Wöchentliche Voll-Backups
   • Teste die Wiederherstellung regelmäßig
5. Monitoring:
   • Überwache Container-Logs
   • Setze Alerts für kritische Fehler
   • Überwache Ressourcen-Nutzung

Nächste Schritte

Nach erfolgreicher Installation kannst du:

1. Weitere Benutzer einladen: Erstelle Accounts für deine Community
2. Räume erstellen: Organisiere deine Kommunikation in Räumen
3. Bridges einrichten: Verbinde mit anderen Chat-Services
4. Bots hinzufügen: Automatisiere Aufgaben mit Matrix-Bots
5. Custom Branding: Passe Element an dein Branding an

Fazit

Mit diesem Setup hast du einen vollständig funktionsfähigen Matrix-Server mit:

• ✅ Sichere, verschlüsselte Kommunikation
• ✅ Voice- und Video-Calls
• ✅ Federation mit anderen Servern
• ✅ Automatisches SSL
• ✅ Moderne Web-Client
• ✅ Admin-Interface

Für weitere Informationen und fortgeschrittene Konfigurationen schaue in die offizielle Synapse-Dokumentation.

Viel Erfolg mit deinem Matrix-Server! 💬🔐

Docker Compose Konfiguration

Hier ist die vollständige docker-compose.yml Datei:

services:
  traefik:
    image: traefik:v3.0
    restart: unless-stopped
    command:
      # Providers
      - --providers.docker=true
      - --providers.docker.exposedbydefault=false

      # Entrypoints
      - --entrypoints.web.address=:80
      - --entrypoints.websecure.address=:443
      - --entrypoints.federation.address=:8448
      #- --entrypoints.turn-udp.address=:3478/udp
      #- --entrypoints.turn-tcp.address=:3478/tcp
      #- --entrypoints.turns-udp.address=:5349/udp
      #- --entrypoints.turns-tcp.address=:5349/tcp

      # HTTP -> HTTPS redirect
      - --entrypoints.web.http.redirections.entrypoint.to=websecure
      - --entrypoints.web.http.redirections.entrypoint.scheme=https

      # ACME/Let's Encrypt
      - --certificatesresolvers.le.acme.tlschallenge=true
      - --certificatesresolvers.le.acme.email=deine-email@deine-domain.de
      - --certificatesresolvers.le.acme.storage=/letsencrypt/acme.json

      # Optional: set to DEBUG if you need ACME diagnostics
      # - --log.level=DEBUG

      # Optional: dashboard on internal socket only (no port published)
      - --api.dashboard=true
    ports:
      - "80:80"
      - "443:443"
      - "8448:8448"
      #- "3478:3478/udp"
      #- "3478:3478/tcp"
      #- "5349:5349/udp"
      #- "5349:5349/tcp"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./traefik/acme.json:/letsencrypt/acme.json

  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: synapse
      # Ensure C collation for Synapse
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --lc-collate=C --lc-ctype=C"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U synapse"]
      interval: 10s
      timeout: 5s
      retries: 10
    volumes:
      - dbdata:/var/lib/postgresql/data

  synapse:
    image: matrixdotorg/synapse:latest
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      # Keep this aligned with homeserver.yaml server_name
      SYNAPSE_SERVER_NAME: ${SYNAPSE_SERVER_NAME}
      SYNAPSE_REPORT_STATS: ${SYNAPSE_REPORT_STATS}
      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
      AWS_DEFAULT_REGION: ${AWS_DEFAULT_REGION}
      AWS_S3_ADDRESSING_STYLE: ${AWS_S3_ADDRESSING_STYLE}
    volumes:
      - ./synapse:/data
      - ./whatsapp/:/whatsapp/
      #- mw_data:/data
    ports:
      - "8008:8008"
    labels:
      - traefik.enable=true

      # Client API via 443
      - traefik.http.routers.synapse-web.rule=Host(`matrix.deine-domain.de`) && (PathPrefix(`/_matrix`) || PathPrefix(`/_synapse`))
      - traefik.http.routers.synapse-web.entrypoints=websecure
      - traefik.http.routers.synapse-web.tls.certresolver=le
      - traefik.http.routers.synapse-web.service=synapse-web
      - traefik.http.services.synapse-web.loadbalancer.server.port=8008
      - traefik.http.middlewares.synapse-buf.buffering.maxRequestBodyBytes=0
      - traefik.http.routers.synapse-web.middlewares=synapse-buf

      # Federation via 8448
      - traefik.http.routers.synapse-fed.rule=Host(`matrix.deine-domain.de`) && PathPrefix(`/_matrix`)
      - traefik.http.routers.synapse-fed.entrypoints=federation
      - traefik.http.routers.synapse-fed.tls.certresolver=le
      - traefik.http.routers.synapse-fed.service=synapse-fed
      - traefik.http.services.synapse-fed.loadbalancer.server.port=8008

  element:
    image: vectorim/element-web:latest
    restart: unless-stopped
    depends_on:
      - synapse
    volumes:
      # Provide your Element config
      - ./element/config.json:/app/config.json:ro
    labels:
      - traefik.enable=true
      - traefik.http.routers.element.rule=Host(`chat.deine-domain.de`)
      - traefik.http.routers.element.entrypoints=websecure
      - traefik.http.routers.element.tls.certresolver=le
      - traefik.http.routers.element.service=element
      - traefik.http.services.element.loadbalancer.server.port=80

  admin:
    image: etkecc/synapse-admin
    container_name: admin
    environment:
      REACT_APP_SERVER: https://matrix.deine-domain.de
      TZ: Europe/Berlin
    ports:
      - "8081:80"
    restart: unless-stopped

  certs-dumper:
    image: ldez/traefik-certs-dumper:latest
    restart: unless-stopped
    depends_on:
      - traefik
    volumes:
      - ./traefik/acme.json:/acme.json:ro
      - ./certs:/out
    env_file:
      - .env
    environment:
      # Export-Modus: directory mit fullchain.pem und privkey.pem pro Domain
      - DOMAIN=${TURN_DOMAIN}
    entrypoint:
      - sh
      - -c
      - |
        set -e
        while true; do
          traefik-certs-dumper file --version v2 --watch=false --source /acme.json --domain-subdir --dest /out
          if [ -f "${CERTS_PATH}/certificate.crt" ]; then
            chown 0:65534 "${CERTS_PATH}/certificate.crt" || true
            chmod 0640 "${CERTS_PATH}/certificate.crt" || true
          fi
          if [ -f "${CERTS_PATH}/privatekey.key" ]; then
            chown 0:65534 "${CERTS_PATH}/privatekey.key" || true
            chmod 0640 "${CERTS_PATH}/privatekey.key" || true
          fi
          sleep 3600
        done

  coturn:
    image: coturn/coturn:latest
    container_name: coturn
    restart: unless-stopped
    depends_on:
      - certs-dumper
    user: "root:root"
    entrypoint:
      - sh
      - -c
      - |
        set -e
        #echo "Waiting for $${CERTS_PATH}/certificate.crt and $${CERTS_PATH}/privatekey.key ..."
        #for i in $$(seq 1 180); do
        #  [ -f "$${CERTS_PATH}/certificate.crt" ] && [ -f "$${CERTS_PATH}/privatekey.key" ] && break
        #  sleep 1
        #done
        #[ -f "$${CERTS_PATH}/certificate.crt" ] && [ -f "$${CERTS_PATH}/privatekey.key" ] || { echo "Certs missing after 180s"; exit 1; }

        exec turnserver \
          --log-file=stdout \
          --no-cli \
          --fingerprint \
          --listening-port=3478 \
          --tls-listening-port=5349 \
          --use-auth-secret \
          --static-auth-secret="$${TURN_STATIC_AUTH_SECRET}" \
          --realm="$${TURN_REALM}" \
          --min-port=49160 \
          --max-port=49200 \
          --cert="$${CERTS_PATH}/certificate.crt" \
          --pkey="$${CERTS_PATH}/privatekey.key" \
          --no-tlsv1 \
          --stale-nonce=600 \
          --total-quota=100 \
          --no-multicast-peers \
          --no-tcp-relay \
          $${EXTERNAL_IP:+--external-ip=$${EXTERNAL_IP}} \
          $${RELAY_IP:+--relay-ip=$${RELAY_IP}}
    environment:
      - CERTS_PATH="/certs/${TURN_DOMAIN}"
      - TURN_REALM=${TURN_REALM}
      - TURN_STATIC_AUTH_SECRET=${TURN_STATIC_AUTH_SECRET}
      - TURN_DOMAIN=${TURN_DOMAIN}
      - EXTERNAL_IP=${EXTERNAL_IP}
      - RELAY_IP=${RELAY_IP}
    network_mode: host
    #ports:
    #  - "3478:3478/tcp"
    #  - "3478:3478/udp"
    #  - "5349:5349/tcp"
    #  - "5349:5349/udp"
    #  - "49160-49200:49160-49200/udp"
    volumes:
      - ./certs:/certs:ro
    healthcheck:
      test: ["CMD-SHELL", "timeout 2 bash -c '</dev/tcp/127.0.0.1/3478' || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 5
    labels:
      - traefik.enable=true
      - traefik.tcp.routers.turn-udp.rule=HostSNI(`*`)
      - traefik.tcp.routers.turn-udp.entrypoints=turn-udp
      - traefik.tcp.routers.turn-udp.service=turn-udp
      - traefik.tcp.services.turn-udp.loadbalancer.server.port=3478
      - traefik.tcp.routers.turn-tcp.rule=HostSNI(`*`)
      - traefik.tcp.routers.turn-tcp.entrypoints=turn-tcp
      - traefik.tcp.routers.turn-tcp.service=turn-tcp
      - traefik.tcp.services.turn-tcp.loadbalancer.server.port=3478
      - traefik.tcp.routers.turns-udp.rule=HostSNI(`*`)
      - traefik.tcp.routers.turns-udp.entrypoints=turns-udp
      - traefik.tcp.routers.turns-udp.service=turns-udp
      - traefik.tcp.services.turns-udp.loadbalancer.server.port=5349
      - traefik.tcp.routers.turns-tcp.rule=HostSNI(`*`)
      - traefik.tcp.routers.turns-tcp.entrypoints=turns-tcp
      - traefik.tcp.routers.turns-tcp.service=turns-tcp
      - traefik.tcp.services.turns-tcp.loadbalancer.server.port=5349

  livekit:
    image: livekit/livekit-server:latest
    restart: unless-stopped
    environment:
      LIVEKIT_PORT: "7880"
      LIVEKIT_RTC_TCP_PORT: "7881"
      LIVEKIT_RTC_UDP_PORT: "7882"        # alternativ Port-Range 50000-60000/udp
      LIVEKIT_KEYS: "${LIVEKIT_API_KEY}: ${LIVEKIT_API_SECRET}"
      LIVEKIT_WEBRTC_USE_EXTERNAL_IP: "true"
    command: >
      --bind 0.0.0.0
      --node-ip 0.0.0.0
      --port 7880
      #--rtc.tcp_port 7881
      #--rtc.udp_port 7882
    labels:
      - traefik.enable=true
      - traefik.http.routers.livekit.rule=Host(`rtc.deine-domain.de`)
      - traefik.http.routers.livekit.entrypoints=websecure
      - traefik.http.routers.livekit.tls.certresolver=le
      - traefik.http.middlewares.livekit-strip.stripprefix.prefixes=/livekit/sfu
      - traefik.http.routers.livekit.middlewares=livekit-strip
      - traefik.http.services.livekit.loadbalancer.server.port=7880
    ports:
      - "7881:7881/tcp"     # WebRTC TCP fallback
      - "7882:7882/udp"     # WebRTC UDP (UDP-Mux)
      # Falls du statt UDP-Mux lieber Range nutzt: 50000-60000/udp publishen

  lk-jwt:
    image: ghcr.io/element-hq/lk-jwt-service:latest
    restart: unless-stopped
    environment:
      LIVEKIT_URL: "wss://rtc.deine-domain.de/livekit/sfu"   # via Traefik auf 7880
      LIVEKIT_KEY: "${LIVEKIT_API_KEY}"
      LIVEKIT_SECRET: "${LIVEKIT_API_SECRET}"
      # optional: RATE_LIMIT, LOG_LEVEL usw.
    labels:
      - traefik.enable=true
      # Route: Host + Pfadpräfix
      - traefik.http.routers.lkjwt.rule=Host(`jwt.deine-domain.de`)
      - traefik.http.routers.lkjwt.entrypoints=websecure
      - traefik.http.routers.lkjwt.tls.certresolver=le
      - traefik.http.services.lkjwt.loadbalancer.server.port=8080

      # CORS freischalten (sonst blockt der Browser die JWT-Anfrage)
      - traefik.http.middlewares.lkjwt-cors.headers.accesscontrolallowmethods=GET,OPTIONS
      - traefik.http.middlewares.lkjwt-cors.headers.accesscontrolallowheaders=*
      - traefik.http.middlewares.lkjwt-cors.headers.accesscontrolalloworiginlist=*
      - traefik.http.middlewares.lkjwt-cors.headers.addvaryheader=true

      # Middlewares anwenden (Reihenfolge egal)
      - traefik.http.routers.lkjwt.middlewares=lkjwt-cors

  wellknown:
    image: nginx:alpine
    volumes:
      - ./well-known:/usr/share/nginx/html/.well-known:ro
    labels:
      - traefik.enable=true
      - traefik.http.routers.wellknown.rule=Host(`matrix.deine-domain.de`) && PathPrefix(`/.well-known/matrix`)
      - traefik.http.routers.wellknown.entrypoints=websecure
      - traefik.http.routers.wellknown.tls.certresolver=le
      - traefik.http.services.wellknown.loadbalancer.server.port=80

  mw-db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_DB: mautrix_whatsapp
      POSTGRES_USER: mautrix
      POSTGRES_PASSWORD: ${MW_POSTGRES_PASSWORD:-change_me}
    volumes:
      - mw_db:/var/lib/postgresql/data

  mautrix-whatsapp:
    image: dock.mau.dev/mautrix/whatsapp:latest
    restart: unless-stopped
    depends_on:
      - mw-db
    volumes:
      - ./whatsapp/:/data/
    ports:
      - "29318:29318"    # AppService-Callback Port für Synapse
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:29318/health"]
      interval: 30s
      timeout: 5s
      retries: 5

volumes:
  dbdata:
  mw_db:
  mw_data:

Wichtig: Ersetze alle deine-domain.de Einträge in der docker-compose.yml mit deiner tatsächlichen Domain!

Was ist Keycloak?

Keycloak ist eine umfassende Lösung für die Verwaltung von Benutzeridentitäten und Zugriffsrechten. Es ermöglicht dir:

• Single Sign-On (SSO) zwischen verschiedenen Anwendungen
• OAuth 2.0 und OpenID Connect für moderne Authentifizierungsflows
• Social Login Integration (Google, Facebook, GitHub, etc.)
• Benutzerverwaltung mit Self-Service-Registrierung
• Rollen- und Rechteverwaltung (RBAC)
• Zwei-Faktor-Authentifizierung (2FA)
• Token-Management für JWT und SAML

Voraussetzungen

Bevor wir mit der Installation beginnen, stelle sicher, dass du folgende Tools auf deinem System installiert hast:

• Docker - Download
• Docker Compose - Download

Installation prüfen

Überprüfe, ob Docker und Docker Compose installiert sind:

docker --version
docker compose version

Schritt 1: Repository klonen

Klone das Keycloak Docker-Setup Repository:

git clone https://gitlab.com/pazdzewicz_docker/keycloak
cd keycloak

Dieses Repository enthält eine vorkonfigurierte Docker Compose-Datei für Keycloak mit PostgreSQL.

Schritt 2: Docker Images herunterladen

Lade die notwendigen Docker Images herunter:

docker compose pull

Dieser Befehl lädt die neuesten Images für Keycloak und PostgreSQL herunter. Je nach Internetverbindung kann dies einige Minuten dauern.

Schritt 3: Umgebungsvariablen konfigurieren

Erstelle eine .env Datei basierend auf der env.template Datei im Repository:

cp env.template .env

Öffne die .env Datei und passe die Werte an deine Bedürfnisse an. Hier sind die wichtigsten Konfigurationsoptionen:

Umgebungsvariablen im Detail

Die docker-compose.yml Datei verwendet folgende Umgebungsvariablen:

environment:
  JAVA_OPTS_APPEND: "${JAVA_OPTS_APPEND}"
  KC_HEALTH_ENABLED: "${KC_HEALTH_ENABLED}"
  KC_HTTP_ENABLED: "${KC_HTTP_ENABLED}"
  KC_METRICS_ENABLED: "${KC_METRICS_ENABLED}"
  KC_FEATURES: "${KC_FEATURES}"
  KC_FEATURES_DISABLED: "${KC_FEATURES_DISABLED}"
  KC_HOSTNAME_URL: "${KC_HOSTNAME_URL}"
  KC_PROXY: "${KC_PROXY}"
  KC_DB: "${KC_DB}"
  KC_DB_URL: "${KC_DB_URL}"
  KC_DB_USERNAME: "${KC_DB_USERNAME}"
  KC_DB_PASSWORD: "${KC_DB_PASSWORD}"
  KEYCLOAK_ADMIN: "${KEYCLOAK_ADMIN}"
  KEYCLOAK_ADMIN_PASSWORD: "${KEYCLOAK_ADMIN_PASSWORD}"

Wichtige Konfigurationsoptionen

Java-Optionen:

• JAVA_OPTS_APPEND: Zusätzliche JVM-Parameter (z.B. für Memory-Einstellungen)

Health & Monitoring:

• KC_HEALTH_ENABLED: Aktiviert Health-Check-Endpunkte (Standard: true)
• KC_METRICS_ENABLED: Aktiviert Metriken-Endpunkte (Standard: false)

Netzwerk & Proxy:

• KC_HTTP_ENABLED: Aktiviert HTTP-Zugriff (Standard: true)
• KC_HOSTNAME_URL: Die öffentliche URL deines Keycloak-Servers
• KC_PROXY: Proxy-Modus (edge, reencrypt, passthrough, none)

Datenbank:

• KC_DB: Datenbanktyp (postgres, mysql, mariadb, etc.)
• KC_DB_URL: JDBC-Verbindungs-URL zur Datenbank
• KC_DB_USERNAME: Datenbank-Benutzername
• KC_DB_PASSWORD: Datenbank-Passwort

Administration:

• KEYCLOAK_ADMIN: Admin-Benutzername für Keycloak
• KEYCLOAK_ADMIN_PASSWORD: Admin-Passwort für Keycloak

Features:

• KC_FEATURES: Zu aktivierende Features (kommagetrennt)
• KC_FEATURES_DISABLED: Zu deaktivierende Features (kommagetrennt)

Beispiel .env Datei

# Java Options
JAVA_OPTS_APPEND="-Xms512m -Xmx1024m"

# Health & Monitoring
KC_HEALTH_ENABLED=true
KC_METRICS_ENABLED=true

# Network
KC_HTTP_ENABLED=true
KC_HOSTNAME_URL=http://localhost:8080
KC_PROXY=edge

# Database
KC_DB=postgres
KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak
KC_DB_USERNAME=keycloak
KC_DB_PASSWORD=change_me_secure_password

# Admin Credentials
KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=change_me_admin_password

# Features
KC_FEATURES=token-exchange,admin-fine-grained-authz
KC_FEATURES_DISABLED=

Sicherheitshinweis: Ändere die Passwörter in deiner .env Datei! Verwende starke, eindeutige Passwörter für Production-Umgebungen.

Schritt 4: Keycloak starten

Starte die Keycloak-Container im Hintergrund:

docker compose up -d

Der -d Flag startet die Container im Detached-Modus (im Hintergrund). Du kannst den Status der Container mit folgendem Befehl überprüfen:

docker compose ps

Die Container sollten jetzt laufen. Keycloak ist standardmäßig unter http://localhost:8080 erreichbar.

Schritt 5: Erste Anmeldung

Nachdem Keycloak gestartet ist, öffne deinen Browser und navigiere zu:

http://localhost:8080

Du wirst zur Keycloak-Administrationskonsole weitergeleitet. Melde dich mit den in deiner .env Datei konfigurierten Admin-Credentials an:

• Benutzername: Der Wert von KEYCLOAK_ADMIN
• Passwort: Der Wert von KEYCLOAK_ADMIN_PASSWORD

SSL/HTTPS Setup

Für Production-Umgebungen wird dringend empfohlen, HTTPS zu verwenden. Eine bewährte Methode ist, einen Reverse-Proxy wie Traefik vor Keycloak zu betreiben.

Warum Traefik?

Traefik bietet:

• Automatische SSL-Zertifikate mit Let’s Encrypt
• Reverse-Proxy-Funktionalität
• Load Balancing
• Einfache Konfiguration über Labels

Keycloak hinter einem Reverse-Proxy

Wenn du Keycloak hinter einem Reverse-Proxy betreibst, setze KC_PROXY entsprechend:

• edge: Proxy terminiert SSL, Keycloak läuft auf HTTP (häufigste Konfiguration)
• reencrypt: Proxy terminiert SSL und verschlüsselt erneut zu Keycloak
• passthrough: Proxy leitet SSL-Traffic durch
• none: Kein Proxy (nur für Entwicklung)

Stelle sicher, dass KC_HOSTNAME_URL auf die öffentliche HTTPS-URL zeigt.

Keycloak Administration über CLI

Keycloak bietet umfangreiche CLI-Tools für die Administration. Du kannst in den Keycloak-Container eintreten und diese Tools verwenden.

In den Container eintreten

docker compose exec -it keycloak bash

Oder direkt zum _bin Verzeichnis:

docker compose exec -it keycloak /bin/bash

kc.sh verwenden

Das kc.sh Skript ist das Hauptwerkzeug für die Keycloak-Administration über die CLI:

cd /opt/keycloak
./bin/kc.sh --help

Verfügbare CLI-Kommandos

Keycloak bietet verschiedene Kommandos für die Administration:

Realm-Verwaltung:

• Realm exportieren: ./bin/kc.sh export --realm myrealm
• Realm importieren: ./bin/kc.sh import --file /path/to/realm.json

Datenbank-Verwaltung:

• Datenbank exportieren: Backup-Skripte im _bin/ Verzeichnis
• Datenbank importieren: Restore-Skripte im _bin/ Verzeichnis

Nützliche Skripte im _bin/ Verzeichnis

Das Repository enthält verschiedene nützliche Skripte:

• Realm Export/Import: Automatisierte Realm-Verwaltung
• Datenbank Backup: Regelmäßige Backups für Disaster Recovery
• Konfigurationsmanagement: Skripte zur Konfigurationsverwaltung

Diese Skripte sind besonders nützlich für:

• Regelmäßige Backups mit Tools wie Restic oder ähnlichen Backup-Lösungen
• Automatisierte Deployments in CI/CD-Pipelines
• Disaster Recovery Szenarien

Container-Logs überwachen

Um die Logs von Keycloak zu überprüfen:

docker compose logs -f keycloak

Für alle Container gleichzeitig:

docker compose logs -f

Erste Schritte mit Keycloak

Nach der erfolgreichen Installation kannst du:

1. Einen Realm erstellen: Ein Realm ist ein isolierter Bereich für Benutzer, Clients und Konfigurationen
2. Clients konfigurieren: Registriere deine Anwendungen als Clients
3. Benutzer erstellen: Füge Benutzer manuell hinzu oder aktiviere Self-Registration
4. Rollen definieren: Erstelle Rollen und weise sie Benutzern zu
5. Identity Provider verbinden: Integriere Social Login oder andere Identity Provider

Häufige Probleme und Lösungen

Problem: Container startet nicht

Lösung:

• Überprüfe die Logs: docker compose logs keycloak
• Stelle sicher, dass der PostgreSQL-Container läuft: docker compose ps
• Überprüfe die .env Datei auf korrekte Werte

Problem: Datenbankverbindungsfehler

Lösung:

• Überprüfe, ob PostgreSQL läuft: docker compose ps postgres
• Verifiziere die Datenbank-Credentials in der .env Datei
• Stelle sicher, dass KC_DB_URL korrekt formatiert ist

Problem: Port bereits belegt

Lösung:

• Finde den Prozess, der Port 8080 verwendet: sudo lsof -i :8080
• Ändere den Port in der docker-compose.yml Datei
• Oder beende den konfliktierenden Prozess

Problem: Admin-Login funktioniert nicht

Lösung:

• Überprüfe, ob die Admin-Credentials in der .env Datei korrekt sind
• Stelle sicher, dass der Container vollständig gestartet ist
• Warte einige Sekunden nach dem Start, bevor du dich anmeldest

Problem: Keycloak startet sehr langsam

Lösung:

• Erhöhe die Java Memory-Optionen: JAVA_OPTS_APPEND="-Xms1024m -Xmx2048m"
• Überprüfe die verfügbaren Systemressourcen
• Stelle sicher, dass die Datenbank schnell genug ist

Best Practices

1. Sicherheit:
   • Verwende starke Passwörter für Admin- und Datenbank-Zugänge
   • Setze Keycloak hinter einen Reverse-Proxy mit SSL
   • Aktualisiere Keycloak regelmäßig auf die neueste Version
2. Backups:
   • Führe regelmäßige Backups der Datenbank durch
   • Exportiere wichtige Realms regelmäßig
   • Teste die Wiederherstellung von Backups
3. Monitoring:
   • Aktiviere Health-Checks: KC_HEALTH_ENABLED=true
   • Aktiviere Metriken: KC_METRICS_ENABLED=true
   • Überwache Container-Logs regelmäßig
4. Performance:
   • Passe Java Memory-Optionen an deine Hardware an
   • Verwende eine leistungsstarke Datenbank
   • Cache-Konfiguration für Production optimieren

Nächste Schritte

Nach erfolgreicher Installation kannst du:

1. Realms konfigurieren: Richte deine ersten Realms ein
2. Clients registrieren: Verbinde deine Anwendungen mit Keycloak
3. Social Login aktivieren: Integriere Google, GitHub oder andere Provider
4. Custom Themes erstellen: Passe das Aussehen der Login-Seiten an
5. User Federation einrichten: Verbinde externe User-Datenbanken

Fazit

Dieses Setup bietet dir eine solide Grundlage für die Verwendung von Keycloak mit Docker und PostgreSQL. Mit dieser Konfiguration hast du eine vollständig funktionsfähige Identity-Management-Lösung, die du nach deinen Bedürfnissen anpassen kannst.

Für fortgeschrittene Konfigurationen und Features schaue in die offizielle Keycloak-Dokumentation.

Viel Erfolg mit deinem Keycloak-Setup! 🔐

Wie wir bereits im Artikel Kubernetes Preisvergleich festgestellt haben, bietet Hetzner ein exzellentes Preis-Leistungs-Verhältnis für Kubernetes-Cluster. Die Kombination aus leistungsfähiger Hardware und attraktiven Preisen macht Hetzner zu einer idealen Wahl für produktive Umgebungen.

In diesem Beitrag zeigen wir euch, wie wir auf den Dedicated Servern von Hetzner einen stabilen und skalierbaren Kubernetes-Cluster einrichten können. Dabei gehen wir Schritt für Schritt durch alle notwendigen Konfigurationen und Best Practices – vom Server-Setup bis hin zur Bereitstellung von Anwendungen. Wir werden folgende Themen abdecken:

1. Vorbereitungen und Anforderungen – Welche Voraussetzungen sollten erfüllt sein, und wie wählen wir die richtige Serverkonfiguration?
2. Installation von Proxmox – Eine detaillierte Anleitung zur Installation und Konfiguration von Proxmox auf den Hetzner-Servern.
3. Konfiguration von Proxmox – Wie wir den Proxmox Cluster für unseren Kubernetes Cluster perfekt vorbereiten.
4. Installation von Kubernetes – Eine detaillierte Anleitung zur Installation und Konfiguration von Kubernetes auf den Hetzner-Servern.
5. Konfiguration von Kubernetes – Die Konfiguration unseres Kubernetes Clusters.

Lasst uns gemeinsam den gesamten Prozess durchlaufen, damit euer Kubernetes-Cluster auf Hetzner bereit für den produktiven Einsatz ist!

Vorbereitungen und Anforderungen

Um einen produktiven Kubernetes-Cluster auf Hetzner aufzubauen, benötigen wir mindestens drei Dedicated Server, die idealerweise über die folgende Ausstattung verfügen.

Für die gesamte Infrastruktur:

• (Optional) 12-Port-10G-Switch: Ein solcher Switch wird benötigt, wenn wir ein dediziertes 10G-Netzwerk für unseren Cluster planen. Somit können wir 10G Bandbreite für Ceph und 10G Bandbreite für unser SDN bereitstellen. Der Netzwerk-Uplink sollte auch über den Switch erfolgen.
• (Optional) 8-Port-1G-Switch: Über diesen Switch können wir die Cluster-Kommunikation für Proxmox vornehmen.

Pro Node:

• Sollten im gleichen Rack bereitgestellt werden
• (Optional) Benötigen (vorerst) keine öffentliche IPv4 Adressen
• Mindestens 2x zusätzliche Festplatten: Diese sind optional, aber für die Nutzung eines verteilten Speichersystems wie Ceph erforderlich. Alternativ kann auch lokaler LVM-Storage verwendet werden.
• (Optional) Intel X520-DA2 mit mindestens 2x 10G-Schnittstellen: Beide 10G Uplinks mit dem 10G Switch verbinden.
• (Optional) OnBoard NIC 1G: Alle Server mit 1G Switch verbinden

Die zusätzlichen Optionen sollten während der Bestellung im Bemerkungsfeld angegeben werden, da es sich hierbei nicht um eine Standardbestellung handelt. Ein Hetzner-Datacenter-Techniker wird diese speziellen Anforderungen individuell bearbeiten.

Eine kostengünstige Beispielkonfiguration könnte wie folgt aussehen. Beachte, dass du natürlich selbst entscheiden kannst, welches System am besten zu deinen Anforderungen passt.

Hinweis: Nach der Installation der Hardware empfiehlt es sich, die kostenlosen Storage-Boxen BX10 für die Server zu aktivieren und darauf SAMBA/CIFS einzurichten. Diese zusätzlichen Speicherlösungen eignen sich hervorragend, um Images und Backups sicher extern zu speichern. Für den direkten Einsatz als VM- oder Container-Diskspeicher sind sie jedoch aufgrund von Leistungs- und Latenzbeschränkungen weniger empfehlenswert.

Installation von Proxmox

Die einzelnen Server sind nun bereitgestellt und entweder über eine öffentliche IPv4- oder IPv6-Adresse per SSH erreichbar. Aktuell befinden wir uns im Hetzner Rescue-System, einem Linux-basierten System, das über PXE gebootet wird. Dieses Rescue-System ermöglicht es uns, grundlegende Wartungsarbeiten durchzuführen, wie beispielsweise das Mounten der Server-Disks. Zudem können wir über den Befehl chroot in das Dateisystem des Servers wechseln, um Konfigurationen oder Reparaturen direkt am installierten Betriebssystem vorzunehmen. Mehr zu dem Hetzner Rescue-System hier.

Wir werden das Proxmox-on-Debian-Bookworm-Image mithilfe des Tools installimage installieren und dabei das Betriebssystem nach unseren Anforderungen konfigurieren. Achte darauf, die Konfiguration entsprechend deiner Infrastruktur anzupassen – dies betrifft insbesondere die Festplatteneinstellungen, das Software-RAID und das LVM-Setup. Passe die Partitionierung und Speicherstruktur so an, dass sie optimal zu deinem Setup und den spezifischen Anforderungen deiner Serverumgebung passen.

Achte darauf, dass der Hostname ein eindeutiger FQDN (Fully Qualified Domain Name) ist, also eine vollständige Domain, die auf die öffentliche IPv4- oder IPv6-Adresse verweist und von außen erreichbar ist. Andernfalls kann es zu Problemen im Proxmox-Cluster kommen, da dieser auf die Erreichbarkeit der Hostnamen angewiesen ist. Es empfiehlt sich außerdem, alle Systeme im Cluster in der Datei /etc/hosts zu hinterlegen, um eine stabile Namensauflösung innerhalb des Netzwerks zu gewährleisten.

Du kannst einzelne Festplatten mithilfe des Symbols # von der Konfiguration ausschließen, was besonders für den Einsatz mit Ceph empfohlen wird. Wenn du hingegen nur ein Local-LVM verwenden möchtest, kannst du diese Festplatten in die Konfiguration aufnehmen. Du hast außerdem die Flexibilität, selbst zu entscheiden, ob du die NVMe-SSDs für Ceph oder für den lokalen Speicher nutzen möchtest. Diese Einstellungen sind anpassbar und sollten entsprechend deinen Anforderungen und der gewünschten Speicherarchitektur vorgenommen werden.

DRIVE 1 /dev/sda
DRIVE 2 /dev/sda
#DRIVE 3 /dev/sdb
#DRIVE 3 /dev/sdc

SWRAID 1
SWRAIDLEVEL 1

BOOTLOADER grub

HOSTNAME proxmox0[1-3].[deinedomain]

PART   /boot  ext3        2G
PART   lvm    proxmox    all

LV  proxmox  root  /     ext4  50G
LV  proxmox  swap  swap  swap  16G
LV  proxmox  home  /home xfs   15G
LV  proxmox  opt   /opt  xfs   15G
LV  proxmox  var   /var  xfs   50G

IMAGE /root/images/Debian-bookworm-latest-amd64-base.tar.gz

Nachdem der Server erfolgreich installiert wurde und Proxmox gebootet ist, können wir mit der Konfiguration der Proxmox-Infrastruktur fortfahren. In den nächsten Schritten richten wir die Netzwerkparameter, die Cluster-Einstellungen sowie die Speicher- und Backup-Optionen ein, um eine stabile und skalierbare Umgebung für unsere Virtualisierungs- und Container-Workloads zu schaffen.

Konfiguration von Proxmox

Hetzner vSwitch

Für die weitere Konfiguration wechseln wir erneut in den Hetzner Robot und richten dort einen vSwitch ein. Dieser befindet sich auf der Übersichtsseite der Dedicated Server. Wir wählen einen Namen sowie eine VLAN-ID aus; in diesem Beispiel verwenden wir die VLAN-ID 4000 und fügen alle unsere Server in den vSwitch ein.

Im nächsten Schritt konfigurieren wir den vSwitch in der Datei /etc/network/interfaces. Achte darauf, dass sich die Namen deiner Netzwerkinterfaces sowie die IP-Adressen je nach Serverkonfiguration unterscheiden können. Passe die Konfiguration daher an deine spezifischen Netzwerkdetails an.

auto lo
iface lo inet loopback

iface lo inet6 loopback

auto enp35s0
iface enp35s0 inet static
        address [SERVER IPv4 ADDRESS CIDR]
        gateway [SERVER IPv4 GATEWAY]
# Public Network v4

iface enp35s0 inet6 static
        address [SERVER IPv6 ADDRESS CIDR]
        gateway fe80::1
# Public Network v6

auto enp35s0.4000
iface enp35s0.4000 inet manual
# vSwitch VLAN

auto vmbr4000
iface vmbr4000 inet static
        address 10.0.1.2/24 # 10.0.1.2 für proxmox01, 10.0.1.3 für proxmox02 und 10.0.1.4 für proxmox03
        bridge-ports enp35s0.4000
        bridge-stp off
        bridge-fd 0
        mtu 1400
        up route add -net 10.0.0.0 netmask 255.255.0.0 gw 10.0.1.1 dev vmbr4000
        post-up iptables -t nat -A POSTROUTING -s '10.0.1.0/24' -o enp35s0 -j MASQUERADE
        post-down iptables -t nat -D POSTROUTING -s '10.0.1.0/24' -o enp35s0 -j MASQUERADE
# vSwitch vmbr4000

source /etc/network/interfaces.d/*

In dieser Netzwerk-Konfiguration richten wir zudem NAT ein, sodass VMs im vmbr4000-Netzwerk über das Internet kommunizieren können. Da unsere Kubernetes-Nodes keine öffentlichen IPv4-Adressen benötigen, reicht es aus, ihnen den Zugriff auf das Internet über NAT bereitzustellen.

Die Server sollten nun über die IPv4 Adressen erreichbar sein:

ping 10.0.1.3
ping 10.0.1.4

Zusätzlich besteht die Möglichkeit, den vSwitch bei Bedarf mit unseren Hetzner Cloud VMs zu verknüpfen. Dadurch können wir eine nahtlose Verbindung zwischen den Dedicated Servern und den Cloud-Instanzen herstellen, was besonders nützlich ist, wenn Kubernetes-Cluster über mehrere Umgebungen hinweg skaliert werden sollen oder zusätzliche Ressourcen aus der Cloud eingebunden werden. Diese Verknüpfung ermöglicht eine flexible, hybride Infrastruktur, in der sowohl Dedicated Server als auch Cloud-Ressourcen effizient in einem gemeinsamen Netzwerk arbeiten.

Proxmox Cluster

Da die Systeme nun miteinander kommunizieren können, stelle sicher, dass alle Server in der Datei /etc/hosts eingetragen sind. Verwende dafür die IP-Adressen aus dem 10.0.1.0/24-Bereich, da wir über dieses Subnetz die Cluster-Kommunikation aufbauen möchten.

Auf dem Server proxmox01 gehen wir zu Datacenter -> Cluster -> Create Cluster und wählen als Cluster-Netzwerk unser 1G-Netzwerk aus.

Auf den Servern proxmox02 und proxmox03 verwenden wir die Join Information, um dem Cluster beizutreten. Achte dabei darauf, immer das richtige Cluster-Netzwerk auszuwählen, um eine stabile und einheitliche Verbindung im gesamten Cluster sicherzustellen.

Proxmox SDN

Um das Proxmox Software Defined Networking (SDN) zu aktivieren, müssen wir zunächst einige zusätzliche Pakete installieren, die in der Standard-Proxmox-Installation nicht enthalten sind. Diese Pakete erweitern die Netzwerkkapazitäten und erlauben die Konfiguration von SDN-Features

apt -y update
apt -y install libpve-network-perl frr-pythontools

Damit haben wir nun die Grundlage geschaffen, das Software-Defined Network (SDN) direkt über die Proxmox-Oberfläche weiter zu konfigurieren. So können wir Netzwerkressourcen zentral verwalten, virtuelle Netzwerke einrichten und nahtlos auf die erweiterten SDN-Funktionen zugreifen, um den Netzwerkverkehr flexibel und effizient zu steuern.

Als nächsten Schritt wechseln wir in die Proxmox-Oberfläche und navigieren zu Datacenter -> SDN -> Options, um dort einen evpn-Controller zu erstellen. Dieser evpn-Controller ermöglicht die Nutzung eines Ethernet VPNs innerhalb der SDN-Umgebung, wodurch virtuelle Netzwerke effizient über mehrere Hosts hinweg verwaltet und verteilt werden können.

• ASN: Wert 65000 belassen.
• Peers: Dort werden alle Proxmox Nodes eingetragen und alle Kubernetes Master Nodes (ich nutze hier den Bereich 10.0.2.21 - 10.0.2.23 für meine Kubernetes Master). Beispiel-Wert: 10.0.1.2,10.0.1.3,10.0.1.4,10.0.2.21,10.0.2.22,10.0.2.23.

Als nächsten Schritt navigieren wir zu Datacenter -> SDN -> Zones und erstellen eine EVPN-Zone. Hier sind einige Beispielwerte für die Konfiguration:

• ID: vnet
• Controller: den vorher erstellten bgp
• VRF-VXLAN Tag: 4005
• Exit Nodes: proxmox01, proxmox02, proxmox03
• Primary Exit Node: proxmox01
• Exit Nodes Local Routing: Nein
• Advertise Subnets: Ja
• Disable ARP-nd Suppression: Ja
• MTU 1400

Alle weiteren Einstellungen können unverändert bleiben oder bei Bedarf an deine spezifischen Anforderungen angepasst werden. So hast du die Flexibilität, die EVPN-Zone optimal auf die Bedürfnisse deines Netzwerks und Workloads abzustimmen.

Diese Konfiguration ermöglicht eine effiziente Verteilung des Netzwerks über die definierten Knoten und stellt sicher, dass die EVPN-Zone als logisches Netzwerk im gesamten Proxmox-Cluster verfügbar ist. Dadurch können die Kubernetes-Nodes und Proxmox die verwendeten IP-Adressen nahtlos miteinander austauschen, was eine reibungslose Kommunikation und Verwaltung der Netzwerkressourcen innerhalb des Clusters gewährleistet.

Proxmox Storage

Falls ihr Ceph verwenden möchtet, könnt ihr die Installation einfach über die Proxmox-Oberfläche unter Datacenter -> Ceph durchführen. Nach der Installation lassen sich die OSDs und weitere Ceph-Komponenten flexibel konfigurieren und einrichten. Eine detaillierte Anleitung zur kompletten Ceph-Konfiguration würde jedoch den Rahmen dieses Artikels sprengen.

Ich nutze zusätzlich die kostenlosen Storage-Boxen als externen Speicher. Diese bieten eine kosteneffiziente Möglichkeit, Backups, Images und andere wichtige Daten sicher und außerhalb des Hauptservers zu speichern.

Darüber hinaus sollte auch der local-lvm-Speicher angelegt werden. Dazu wählt ihr die Volume Group proxmox aus. Dieser Speicherbereich kann nun für VMs genutzt werden und dient als zusätzlicher Speicherplatz, der bei der Installation noch nicht definiert wurde.

Debian Cloud Image

Um ein Debian Cloud Image für unsere Kubernetes-Nodes bereitzustellen, könnt ihr die folgenden Befehle verwenden:

cd /var/lib/vz/images
wget https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-generic-amd64.qcow2
qm create 9000 --memory 4096 --net0 virtio,bridge=vmbr4000 --scsihw virtio-scsi-pci
qm set 9000 --scsi0 local-lvm:0,import-from=/var/lib/vz/images/debian-12-generic-amd64.qcow2
qm set 9000 --ide2 local-lvm:cloudinit
qm set 9000 --boot order=scsi0
qm set 9000 --serial0 socket --vga serial0
qm template 9000

Dieser Prozess lädt das aktuelle Debian-Cloud-Image für “Bookworm” herunter und erstellt eine Vorlage (template) für die Kubernetes-Nodes mit 4 GB RAM und einer Netzwerkschnittstelle, die über vmbr4000 kommuniziert. Anschließend wird das Image als scsi0 eingebunden und das cloudinit-Laufwerk eingerichtet, um eine Cloud-Init-Konfiguration zu ermöglichen. Mit diesen Einstellungen steht das Image als VM-Vorlage bereit und kann für den schnellen Start weiterer Kubernetes-Nodes genutzt werden.

Installation von Kubernetes

Nun erstellen wir auf jedem unserer Server basierend auf dem Debian Cloud Image jeweils einen Master-Node und einen Worker-Node für den Kubernetes-Cluster. Für die Master-Nodes nutzen wir die IP-Range 10.0.2.21 - 10.0.2.23. Die IP-Adresse 10.0.2.20 wird als Cluster VIP (Virtual IP) reserviert und bleibt frei, um eine hochverfügbare Cluster-Verwaltung zu ermöglichen. Die Worker-Nodes verwenden die IP-Range 10.0.2.31 - 10.0.2.33.

Diese Konfiguration stellt sicher, dass die Master- und Worker-Nodes über dedizierte IP-Adressen kommunizieren können und die Cluster VIP zur Verfügung steht, um den Cluster stabil zu halten und automatisch auf einen anderen Master-Node umzuschalten, falls dies erforderlich ist.

Mit dem in Proxmox integrierten Cloud-Init-Tool können wir grundlegende Einstellungen wie Hostname, Benutzername, SSH-Keys, IP-Konfiguration und mehr direkt an die VM übergeben. Dadurch wird die Ersteinrichtung der VM automatisiert und es sind keine zusätzlichen manuellen Konfigurationen erforderlich. Cloud-Init erleichtert die Verwaltung und Anpassung der Kubernetes-Nodes, sodass sie sofort einsatzbereit sind.

Ich verwende das Tool k3sup, das es mir ermöglicht, auf einfache Weise und direkt von meinem lokalen PC aus einen Kubernetes-Cluster zu erstellen. Mit k3sup lassen sich Kubernetes-Installationen automatisieren und die Knoten schnell verbinden, was den Aufbau eines Clusters erheblich vereinfacht.

k3sup install --ip 10.0.2.21 --tls-san 10.0.2.20 --cluster --k3s-channel latest --k3s-extra-args "--disable servicelb" --local-path $HOME/.kube/config --user kube

Sobald der erste Master-Node bereit ist, installieren wir kube-vip, um die Hochverfügbarkeit des Clusters zu gewährleisten. Zunächst benötigen wir die RBAC-Datei (Role-Based Access Control), um die erforderlichen Berechtigungen für kube-vip festzulegen. Anschließend erstellen wir die Konfigurationsdatei, die die Einstellungen für den VIP (Virtual IP) und die Kommunikation zwischen den Master-Nodes enthält.

Alle folgenden Befehle werden auf unserem Kubernetes-Master-Node 01 (10.0.2.21) ausgeführt:

kubectl apply -f https://kube-vip.io/manifests/rbac.yaml

export VIP=10.0.2.20
export INTERFACE=lo
KVVERSION=$(curl -sL https://api.github.com/repos/kube-vip/kube-vip/releases | jq -r ".[0].name")
alias kube-vip="ctr image pull ghcr.io/kube-vip/kube-vip:$KVVERSION; ctr run --rm --net-host ghcr.io/kube-vip/kube-vip:$KVVERSION vip /kube-vip"

kube-vip manifest daemonset \
    --interface $INTERFACE \
    --address $VIP \
    --inCluster \
    --taint \
    --controlplane \
    --services \
    --bgp \
    --localAS 65000 \
    --bgpRouterID 10.0.2.20 \
    --bgppeers 10.0.1.2:65000::false,10.0.1.3:65000::false,10.0.1.4:65000::false | tee /var/lib/rancher/k3s/server/manifests/kube-vip.yaml

In der Option bgppeers haben wir unsere Proxmox-Nodes hinterlegt. Dadurch kann der Kubernetes-Cluster direkt mitteilen, welche VIPs (Virtual IPs) über BGP (Border Gateway Protocol) angekündigt werden sollen. Diese Konfiguration sorgt dafür, dass die VIPs automatisch über das Netzwerk verteilt werden und die Proxmox-Nodes stets wissen, welche IPs aktiv im Cluster verwendet werden. Dies erhöht die Ausfallsicherheit und verbessert die Netzwerkkommunikation im Cluster erheblich.

Nun fügen wir die restlichen Master-Nodes mit k3sup hinzu:

k3sup join --ip 10.0.2.22 --server-ip 10.0.2.20 --server --k3s-channel latest --user kube
k3sup join --ip 10.0.2.23 --server-ip 10.0.2.20 --server --k3s-channel latest --user kube

Anschließend fügen wir die Worker-Nodes hinzu:

k3sup join --ip 10.0.2.31 --server-ip 10.0.2.20 --k3s-channel latest --user kube
k3sup join --ip 10.0.2.32 --server-ip 10.0.2.20 --k3s-channel latest --user kube
k3sup join --ip 10.0.2.33 --server-ip 10.0.2.20 --k3s-channel latest --user kube

Diese Befehle verbinden die zusätzlichen Master- und Worker-Nodes nahtlos mit dem Cluster, wobei die Cluster-Kommunikation über die VIP 10.0.2.20 läuft. So wird die Hochverfügbarkeit gewährleistet, da die Master-Nodes miteinander synchronisiert werden und die Worker-Nodes ihre Anweisungen zentral über den Cluster erhalten.

Mit dem Befehl kubectl get nodes lässt sich überprüfen, ob alle Knoten erfolgreich dem Cluster beigetreten sind und korrekt arbeiten. Dieser Befehl zeigt eine Liste aller Master- und Worker-Nodes an und gibt ihren aktuellen Status sowie ihre Rollen im Cluster an. So können wir sicherstellen, dass die Clusterstruktur vollständig ist und alle Verbindungen korrekt hergestellt wurden.

$ kubectl get nodes
NAME   STATUS   ROLES                       AGE     VERSION
km1    Ready    control-plane,etcd,master   2d19h   v1.31.2+k3s1
km2    Ready    control-plane,etcd,master   2d19h   v1.31.2+k3s1
km3    Ready    control-plane,etcd,master   2d19h   v1.31.2+k3s1
kw1    Ready    <none>                      4h45m   v1.30.6+k3s1
kw2    Ready    <none>                      2d18h   v1.30.6+k3s1
kw3    Ready    <none>                      4h45m   v1.30.6+k3s1

Die Kubernetes-Installation ist damit abgeschlossen. Alle Knoten sind erfolgreich dem Cluster beigetreten und die grundlegende Konfiguration ist eingerichtet. Der Cluster ist nun einsatzbereit für das Deployment von Anwendungen und die Verwaltung über kubectl.

Konfiguration von Kubernetes

Um LoadBalancer in Kubernetes nutzen zu können, installieren wir zunächst den kube-vip Cloud Controller mit folgendem Befehl:

kubectl apply -f https://raw.githubusercontent.com/kube-vip/kube-vip-cloud-provider/main/manifest/kube-vip-cloud-controller.yaml

Zusätzlich erstellen oder bearbeiten wir eine ConfigMap, um den IP-Bereich für die VIPs (Virtual IPs) festzulegen. In diesem Beispiel verwenden wir den Bereich 10.0.2.200-10.0.2.240:

kubectl create configmap -n kube-system kubevip --from-literal range-global=10.0.2.200-10.0.2.240

Mit dieser Konfiguration können LoadBalancer-Dienste im Kubernetes-Cluster automatisch VIPs aus dem definierten IP-Bereich beziehen und so den externen Zugriff auf Anwendungen ermöglichen. Wir können in der ConfigMap auch öffentliche IP-Adressen aus Failover-Subnetzen eintragen, die wir über den vSwitch gebucht haben. Durch die Integration mit dem SDN und die Nutzung von BGP werden diese IP-Adressen korrekt im Netzwerk geroutet, sodass externe Zugriffe über LoadBalancer-Dienste im Kubernetes-Cluster möglich sind. Diese Flexibilität ermöglicht es uns, VIPs sowohl für interne als auch für öffentliche Dienste zu nutzen und dabei eine zuverlässige Netzwerkstruktur zu gewährleisten.

Wenn wir den mit k3s mitgelieferten Traefik als Ingress verwenden möchten, müssen wir diesen anpassen:

kubectl edit service traefik -n kube-system

Anschließend ändern wir in der Konfiguration des Traefik-Ingress den Wert spec.loadBalancerIP und tragen die öffentliche IP-Adresse ein, über die der Ingress erreichbar sein soll. Damit wird der Traefik-Ingress öffentlich verfügbar und kann extern angesprochen werden.

Dank dieser Einstellung können wir in Kombination mit dem cert-manager automatisch SSL-Zertifikate erstellen und verwalten. Dadurch wird das Deployment von Anwendungen deutlich erleichtert, da HTTPS-Verbindungen zentral und automatisiert abgesichert sind, und die Verwaltung von Zertifikaten erfolgt gebündelt im Cluster.

Tests

Mit diesem Beispiel-Deployment können wir testen, ob die Konfiguration wie gewünscht funktioniert.

Die Datei whoami.yaml definiert ein ReplicaSet mit drei Replikaten der whoami-Anwendung, einen Service zur Bereitstellung der Anwendung und einen Ingress, um die Anwendung extern verfügbar zu machen:

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: whoami
  namespace: default
spec:
  replicas: 3
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
        - name: whoami
          image: traefik/whoami
---
apiVersion: v1
kind: Service
metadata:
  name: whoami
  namespace: default
spec:
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
  selector:
    app: whoami
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: whoami
  namespace: default
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-cloudflare
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  tls:
    - hosts:
        - whoami.peppermint.cloud
      secretName: whoami-peppermint-cloud
  rules:
    - http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: whoami
                port:
                  number: 80

Hinweise:

• Domain: Passe die Domain in tls.hosts auf diejenige an, die öffentlich erreichbar ist.
• ClusterIssuer: Falls der cert-manager nicht installiert ist oder ein anderer Issuer verwendet werden soll, entferne oder ändere die Annotation cert-manager.io/cluster-issuer.

Durch dieses Deployment wird die whoami-Anwendung über den Traefik-Ingress öffentlich verfügbar und sollte HTTPS-Zertifikate über letsencrypt-cloudflare erhalten, falls alles korrekt eingerichtet ist.

Wir können die Funktionalität des Deployments mit einem einfachen curl-Befehl überprüfen:

curl "https://whoami.peppermint.cloud"

Das Ergebnis sollte dann in etwa wie folgt aussehen:

$ curl "https://whoami.peppermint.cloud"
Hostname: whoami-dxrhk
IP: 127.0.0.1
IP: ::1
IP: 10.42.0.8
IP: fe80::ec63:60ff:fee3:42ad
RemoteAddr: 10.42.0.7:36488
GET / HTTP/1.1
Host: whoami.peppermint.cloud
User-Agent: curl/7.88.1
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 10.42.0.1
X-Forwarded-Host: whoami.peppermint.cloud
X-Forwarded-Port: 443
X-Forwarded-Proto: https
X-Forwarded-Server: traefik-57b79cf995-d6ph7
X-Real-Ip: 10.42.0.1

Bei jeder neuen Ausführung von curl ändert sich der Hostname des Containers, der die Anfrage bearbeitet. Das zeigt, dass die Anwendung über mehrere Container repliziert wurde und diese nun auf verschiedenen Hosts verteilt sind. Dadurch wird eine hohe Verfügbarkeit gewährleistet und die Leistung der Anwendung kann durch die Verteilung der Anfragen auf mehrere Instanzen skaliert werden.

Erfolg

Wir haben erfolgreich einen produktiven Kubernetes-Cluster mit BGP-Integration in unserer Proxmox-Infrastruktur eingerichtet. Damit ist die Grundlage für eine hochverfügbare und skalierbare Umgebung geschaffen.

In weiteren Artikeln werden wir uns noch detailliert mit der Einrichtung des Speichers für PersistentVolumeClaims sowie dem HorizontalPodAutoscaling beschäftigen, um die volle Leistungsfähigkeit des Clusters auszuschöpfen.

Für meine Projekte benötige ich regelmäßig zuverlässige Kubernetes Cluster. In der Vergangenheit habe ich gerne managed Kubernetes von DigitalOcean verwendet, jedoch empfand ich dies gelegentlich als zu kostspielig. Selbst für kleinere Projekte musste ich manchmal mehr als 100 € pro Monat bezahlen. Daher habe ich beschlossen, eine Liste verschiedener Cloud-Provider zu erstellen, um die Preise besser vergleichen zu können.

Zusätzlich habe ich ein Bemerkungsfeld eingefügt, das unter anderem meine persönlichen Erfahrungen mit den jeweiligen Providern enthält. In die Liste habe ich nur Anbieter aufgenommen, die ich tatsächlich selbst ausprobiert habe und zu denen ich eine fundierte Meinung entwickeln konnte.

Einleitung - Anwendungs-Stack

Auch stütze ich meinen Preisvergleich auf die notwendigen Ressourcen eines selbst entwickelten Microservice-Anwendungs-Stacks aus folgenden Komponenten:

• Frontend (Phalcon PHP Anwendung, Redis Cache, MySQL Datenbank)
• Backend (Phalcon PHP Anwendung, Redis Cache, MySQL Datenbank)
• CMS (Directus.io API, Redis Cache, PostgreSQL Datenbank)
• User Data (Directus.io API, Redis Cache, PostgreSQL Datenbank)
• Authentication (Keycloak, PostgreSQL Datenbank)
• Logging (Graylog, Elasticsearch, MongoDB Datenbank)

Diverse Anwendungen in dem Stack liegen unter anderem als ReplicaSet vor, das heißt, es gibt mehrere Instanzen von z.B. der Frontend Phalcon PHP Anwendung. Einige, wie zum Beispiel Graylog, sind ausschließlich für administrative Zwecke bestimmt und haben keine Replikate.

Für ein Loader.io-Ergebnis mit 10.000 Benutzern benötigt dieser Anwendungs-Stack mindestens 3 Nodes, wobei jede Node über 4 CPU-Kerne und 16 GB RAM verfügt. Dies ist großzügig dimensioniert, um noch zusätzliche Ressourcen in Reserve zu haben.

Damit habe ich eine Real-Life-Workload abgedeckt, die für die meisten Firmen mit einem mittleren bis großen Online-Shop relevant ist.

Einleitung - Unterteilung

Der Preisvergleich ist in zwei Kategorien unterteilt: Anbieter, die bereits vorkonfigurierte, also managed Kubernetes Cluster anbieten, und Anbieter, auf deren Plattform man Kubernetes Cluster selbst installieren kann.

Preisvergleich

Preisvergleich - Computing

Ich betrachte derzeit nur die reinen Rechenkosten. Zusätzliche Features wie etwa S3-kompatibler Speicher, Blockspeicher, Loadbalancer und Backups kosten in der Regel einen Aufpreis. Möglicherweise aktualisiere ich dieses Dokument in der Zukunft und ziehe diese Kosten ebenfalls in Betracht.

Managed Kubernetes Cluster

Unmanaged Kubernetes Cluster

Fazit

Kubernetes kann ziemlich kostspielig sein, aber es gibt deutliche Preisunterschiede zwischen den verschiedenen Providern. Und manchmal rechtfertigt sich der höhere Preis nicht unbedingt durch einen besseren Kundensupport oder mehr Stabilität. In diesem Zusammenhang bin ich äußerst positiv von Hetzner überrascht. Die Bereitstellung der Rechenleistung erfolgt nicht nur schnell, sondern auch der Support ist herausragend gut. Im Vergleich dazu musste ich bei Amazon Web Services teilweise wirklich lange auf die Bereitstellung warten (über 2 Stunden!) und auch auf eine Antwort des Supports (über 2 Tage). Das ist einfach nicht die hohen Kosten wert!

Natürlich muss jeder für sich entscheiden, welchen Provider er auswählt. Ich bleibe allerdings weiterhin Hetzner für größere Projekte treu!

Gemäß der technischen Dokumentation von Apple ist es auf einem MacBook Pro aus dem Jahr 2021 mit M1 Pro Chip nicht möglich, mehr als zwei externe Displays zu verwenden. Diese technische Begrenzung kann frustrierend sein, insbesondere wenn man, wie ich, gerne drei externe Displays nutzen würde.

Ich benutze, von links nach rechts, folgende Displays: Dell U2421HE (1920 x 1080 Pixel), LG Ultrawide 29UM57-P, (2560 x 1080 Pixel) und erneut einen Dell U2421HE (1920 x 1080 Pixel). Diese Bildschirme eignen sich perfekt für ein Triple-Monitor-Setup, da sie in der Höhe ideal aufeinander abgestimmt sind.

Die Dell-Monitore bieten eine beeindruckende Vielfalt an Anschlussmöglichkeiten, insbesondere der integrierte USB-C-Hub, der sich ideal eignet, um viele Geräte anzuschließen. Die unterschiedlichen Display-Anschlüsse, darunter DisplayPort über USB-C, DisplayPort und HDMI, ermöglichen es mir, mehrere PCs anzuschließen. Aktuell habe ich über DisplayPort einen Windows-Gaming-PC und über HDMI das MacBook angeschlossen. Dabei nutze ich den integrierten HDMI-Anschluss für das MacBook und einen weiteren HDMI-Anschluss, der im Satechi ST-TCMA2M Dock enthalten ist. Leider verfügt der LG-Monitor nur über zwei HDMI-Anschlüsse.

Ausprobieren

Da ich von Natur aus ein Bastler bin und manchmal feststelle, dass technische Dokumentationen nicht immer die ganze Wahrheit abbilden, habe ich versucht, dies herauszufinden, indem ich ein zusätzliches Delock 64074 Dock und einen Anker 310 USB-C zu HDMI Adapter verwendet habe. Die technischen Einschränkungen erwiesen sich mitunter als restriktiver als erhofft, und in diesem Fall hat sich gezeigt, dass die Angaben in der technischen Dokumentation von Apple korrekt sind.

Hilfeschrei

In meiner Verzweiflung habe ich mich auch an die in der Regel sehr hilfreiche Reddit-Community in r/de_EDV gewandt und einen Beitrag verfasst. Leider hat dies nicht zu dem gewünschten Ergebnis geführt.

Lösung

Zufällig bin ich auf einen StarTech.com 107B-USB-HDMI Dual-Monitor-Adapter gestoßen, der es ermöglicht, über USB-C (und auch USB-A) zwei zusätzliche Displays anzuschließen – eines mit einer maximalen Auflösung von 1080p bei 60 Hz und eines mit 4k bei 30 Hz –, beide über HDMI verbunden. Das klang vielversprechend, und ich habe ihn sofort bei Amazon bestellt. Nach der Ankunft habe ich den Adapter sofort angeschlossen, die Treiber von der Webseite für Mac OS heruntergeladen und installiert. Der LG Ultrawide Monitor lief problemlos im erweiterten Modus, und ich konnte endlich alle meine drei Displays nutzen.

Erleichterung

Ich freute mich außerordentlich und war erleichtert, dass ich nun endlich über die gesamte Bildschirmfläche verfügen konnte, die ich vor mir hatte. Mal wieder ein großartiger Erfolg!

Heute möchten wir einen einfachen Cloudflare Tunnel einrichten, um interne Dienste sicher hinter einer Firewall zu betreiben, ohne Ports im Internet freizugeben. Dafür benötigen wir selbstverständlich einen Cloudflare-Account und eine Domain, die bei Cloudflare konfiguriert ist.

Ein Cloudflare Tunnel ist eine Technologie, die es ermöglicht, private Netzwerke sicher mit dem Cloudflare-Netzwerk zu verbinden. Dies geschieht, indem der Datenverkehr von internen Diensten durch verschlüsselte Verbindungen zu Cloudflare-Servern geroutet wird. Dadurch können interne Dienste sicher und zuverlässig über das Internet erreichbar gemacht werden, ohne dass dafür Portweiterleitungen in der Firewall erforderlich sind. Dies erhöht die Sicherheit und schützt interne Ressourcen vor direkten externen Zugriffen.

Einen Tunnel erstellen

Wir loggen uns in unser Cloudflare-Dashboard ein und erstellen unter Zero Trust -> Access -> Tunnels -> Create a tunnel einen neuen Tunnel.

Jetzt vergeben wir einen Namen und klicken auf Save tunnel.

Nun kopieren wir uns den Tunnel Token:

Im nächsten Schritt installieren wir einen Connector. Die Pazdzewicz IT hat dafür einen eigenen optimierten Docker-Container entwickelt.

Connector Installieren

Jetzt melden wir uns auf einem Linux-Server mit vorinstalliertem Docker an und klonen das Repository:

git clone git@gitlab.com:pazdzewicz_docker/cloudflared.git
cd cloudflared

Um den Connector verfügbar zu machen benötigen wir nun das Connector Token aus dem vorherigen Schritt und fügen diesen in unsere .env Datei ein:

cp .env.template .env
nano .env

CLOUDFLARE_TOKEN="<Tunnel Token>"

Anschließend können wir den Tunnel mittels docker-compose starten:

docker-compose pull
docker-compose up -d

Verfügbarkeit überprüfen

In der Übersicht der Tunnels überprüfen wir nun ob der Tunnel HEALTHY ist:

Routen einrichten

Nun klicken wir auf den Tunnel Namen und anschließend auf Configure. Unter Public Hostname -> Add a plublic hostname können wir nun eine öffentliche Subdomain mit einem internen Service verbinden. In diesem Beispiel werden wir unseren internen Entwicklungsserver unter dev.pazdzewicz.de auf der IP 192.168.88.5 verfügbar machen.

Mit Save hostname können wir nun den Hostnamen abspeichern.

Nach dem aufrufen von https://dev.pazdzewicz.de im Web-Browser sollten wir unsere Seite sehen:

Somit ist unser Tunnel nun eingerichtet!

Heute beschreiben wir, wie Sie ganz einfach und schnell einen Minecraft Paper Server in Docker erstellen können.

Minecraft Paper ist eine von der Community entwickelte Server-Software für das beliebte Sandbox-Spiel Minecraft. Es handelt sich um eine Modifikation (Mod) des offiziellen Minecraft-Servers, die auf eine verbesserte Leistung, Stabilität und erweiterte Funktionen abzielt. PaperMC baut auf dem sogenannten “Spigot”-Server auf, der bereits Optimierungen für Server-Performance bietet, und führt zusätzliche Anpassungen und Verbesserungen durch.

Die Hauptmerkmale von Minecraft Paper sind:

• Verbesserte Leistung: PaperMC optimiert die Serverleistung erheblich, um eine flüssigere Spielerfahrung zu gewährleisten, insbesondere auf großen Servern mit vielen Spielern und Plugins.

• Stabilität: Die Software behebt viele der bekannten Fehler und Absturzursachen des offiziellen Servers und bietet eine stabilere Umgebung für Spieler und Administratoren.

• Plugin-Kompatibilität: PaperMC ist mit den meisten Minecraft-Plugins kompatibel, die für Spigot entwickelt wurden. Dies ermöglicht Serveradministratoren, eine breite Palette von Erweiterungen und Anpassungen hinzuzufügen, um ihre Spielerfahrung zu verbessern.

• Aktive Entwicklung: Die PaperMC-Entwicklergemeinschaft arbeitet kontinuierlich an Updates und Verbesserungen, um sicherzustellen, dass der Server auf dem neuesten Stand bleibt und den Anforderungen der Minecraft-Community gerecht wird.

Insgesamt bietet Minecraft Paper eine solide Grundlage für die Erstellung und Verwaltung von Multiplayer-Minecraft-Servern mit verbesserter Leistung und erweiterten Funktionen.

Installation des Docker Containers

Wir beginnen auf einem Linux-System, auf dem Docker und Docker-Compose bereits installiert sind, und klonen das GitLab-Repository für den Minecraft Paper Server.

git clone git@gitlab.com:pazdzewicz_docker/minecraft-paper.git
cd minecraft-paper/

Im Verzeichnis befindet sich bereits eine vorkonfigurierte docker-compose.yml Datei, mit der der Server problemlos gestartet werden kann.

docker-compose pull
docker-compose up -d

Konfiguration des Minecraft Servers

Nun öffnen wir unseren Minecraft Client in der jeweiligen gewählten Version. Und Verbinden uns über Multiplayer -> Add Server.

Dies sollte aufgrund der aktivierten Whitelist nicht möglich sein, ist jedoch ein wichtiger Schritt für das weitere Vorgehen.

Jetzt rufen wir die Protokolle (Logs) des Containers auf.

docker-compose logs spigot

Wir benötigen den Namen und die UUID des Spielers und kopieren beide Informationen.

Wir tragen diese Informationen nun in der Datei settings/whitelist.json ein:

[
  {
    "uuid":"588e037c-17a6-41e6-ab0d-bbde572dde51",
    "name":"RageGuyKai"
  },
  {
    "uuid":"XXXXXX-XXXX-XXXXXX-XXX-XXXXXXXX",
    "name":"Nocheinspieler"
  }
]

Und wenn der Benutzer ein Server Operator (Administrator) sein soll, müssen wir die entsprechenden Informationen in der Datei settings/ops.json eintragen.

[
  {
    "uuid": "588e037c-17a6-41e6-ab0d-bbde572dde51",
    "name": "RageGuyKai",
    "level": 4,
    "bypassesPlayerLimit": false
  },
  {
    "uuid":"XXXXXX-XXXX-XXXXXX-XXX-XXXXXXXX",
    "name":"Nocheinspieler",
    "level": 4,
    "bypassesPlayerLimit": false
  }
]

Lassen Sie uns jetzt den Server einmal neu starten, um die Einstellungen zu bestätigen:

docker-compose restart spigot

Jetzt können wir uns mit dem Minecraft-Server verbinden und unserer Kreativität gemeinsam mit Freunden freien Lauf lassen.

PS: Weitere Server Einstellungen können unter config/ angepasst werden :smile: