Claude Code Nginx: Konfiguration, Reverse Proxy und SSL in Minuten

Nginx ist eines jener Werkzeuge, die man entweder auswendig beherrscht oder bei jedem Einsatz neu nachschlägt. Die Dokumentation ist vollständig, die Community-Ressourcen sind zahlreich — aber der Weg vom Ziel ("ich möchte einen Reverse Proxy vor meiner Node-App") zur funktionierenden Konfiguration ist voller kleiner Stolperstellen: falsche proxy_set_header-Werte, vergessenes upstream-Block, HTTPS-Redirect der HTTP/2 nicht aktiviert.

Claude Code Nginx-Workflows ändern das. Nicht weil sie Nginx einfacher machen — sondern weil Claude Code die Konfiguration generiert, Fehler im laufenden Betrieb diagnostiziert und Performance-Tuning-Vorschläge direkt auf deine nginx.conf anwendet. Dieser Artikel zeigt, wie das konkret aussieht.

1. Was ist Nginx — und warum ist es überall?

Nginx (ausgesprochen "Engine-X") ist ursprünglich als Webserver gestartet, der gleichzeitige Verbindungen effizienter verarbeitet als Apache. Heute ist es in den meisten modernen Infrastrukturen dreifach im Einsatz: als Webserver für statische Dateien, als Reverse Proxy vor Anwendungsservern und als Load Balancer zwischen mehreren Backend-Instanzen.

Warum so verbreitet? Nginx verarbeitet zehntausende gleichzeitige Verbindungen mit minimalem Speicherverbrauch, weil es ein ereignisgesteuertes (non-blocking) Modell verwendet statt eines Thread-pro-Verbindung-Ansatzes. Das macht es zur ersten Wahl für alles, was im öffentlichen Internet steht.

• Webserver: Statische Dateien direkt ausliefern — HTML, CSS, JS, Bilder — ohne Anwendungslogik dazwischen
• Reverse Proxy: Anfragen entgegennehmen und an einen oder mehrere Backend-Dienste weiterleiten
• Load Balancer: Eingehenden Traffic auf mehrere Backend-Instanzen verteilen, Ausfälle erkennen und umleiten

2. Grundkonfiguration: nginx.conf, Server Blocks, Location Blocks

Die Nginx-Konfiguration folgt einer klaren Hierarchie. Oben steht die globale nginx.conf, darunter http-Block, darunter server-Blocks für einzelne virtuelle Hosts, darunter location-Blocks für URL-Pfade.

# /etc/nginx/sites-available/mein-projekt.conf

server {
    listen 80;
    server_name mein-projekt.de www.mein-projekt.de;
    root /var/www/mein-projekt/public;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    location ~* \.(js|css|png|jpg|svg|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Claude Code kann diese Grundstruktur in Sekunden generieren. Der entscheidende Vorteil: Claude Code fragt nach deinem konkreten Anwendungsfall und passt die Konfiguration an, statt eine generische Vorlage zu liefern.

claude "Erstelle eine Nginx server block Konfiguration für eine
statische Next.js App unter /var/www/nextjs-app/out,
Domain: mein-projekt.de, gzip aktivieren, lange Cache-Header
für Assets mit Hash im Dateinamen"

3. Reverse Proxy Setup: proxy_pass und proxy_set_header

Der häufigste Nginx-Einsatz in modernen Stacks: eine Node.js-, Python- oder Go-Anwendung lauscht auf einem lokalen Port, Nginx nimmt die öffentlichen Anfragen entgegen und leitet sie weiter. Das schützt die Anwendung vor dem direkten Internet-Zugriff und ermöglicht SSL-Terminierung, Caching und Kompression auf Nginx-Ebene.

upstream app_backend {
    server 127.0.0.1:3000;
    keepalive 32;
}

server {
    listen 80;
    server_name api.mein-projekt.de;

    location / {
        proxy_pass http://app_backend;
        proxy_http_version 1.1;

        # Wichtig: Original-IP und Host weitergeben
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket-Unterstützung
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Timeouts
        proxy_connect_timeout 60s;
        proxy_send_timeout    60s;
        proxy_read_timeout    60s;
    }
}

Die proxy_set_header-Direktiven sind kritisch: Ohne X-Forwarded-For sieht deine Anwendung nur die lokale Nginx-IP statt der echten Client-IP. Ohne X-Forwarded-Proto weiß sie nicht, ob die originale Anfrage per HTTP oder HTTPS kam — ein häufiger Fehler bei HTTPS-Redirects in der Anwendung selbst.

"Zeige mir die aktuelle proxy_pass-Konfiguration, ich prüfe ob X-Forwarded-For korrekt gesetzt ist und ob keepalive für deinen Traffic sinnvoll ist."

So antwortet Claude Code, wenn du eine bestehende Konfiguration zur Analyse übergibst. Es liest die Datei, erkennt fehlende oder falsche Header und gibt konkrete Korrekturvorschläge — mit Begründung.

4. SSL/TLS mit Let's Encrypt: Certbot, HTTPS-Redirect, HSTS

Heute ist HTTPS kein Optional-Feature mehr — Browser warnen vor unverschlüsselten Seiten, Suchmaschinen bevorzugen HTTPS, und ohne SSL funktionieren HTTP/2 und viele moderne Browser-APIs nicht. Let's Encrypt bietet kostenlose, automatisch erneuerbare Zertifikate. Certbot automatisiert die Installation.

# Certbot installieren und Zertifikat ausstellen
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d mein-projekt.de -d www.mein-projekt.de

Certbot modifiziert die Nginx-Konfiguration automatisch. Das Ergebnis sieht typischerweise so aus:

server {
    listen 443 ssl http2;
    server_name mein-projekt.de www.mein-projekt.de;

    ssl_certificate     /etc/letsencrypt/live/mein-projekt.de/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mein-projekt.de/privkey.pem;

    # Moderne SSL-Konfiguration
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:...;
    ssl_prefer_server_ciphers off;
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 1d;

    # HSTS: Browser merken sich, dass diese Domain immer HTTPS braucht
    add_header Strict-Transport-Security "max-age=63072000" always;

    # ... rest der Konfiguration
}

server {
    listen 80;
    server_name mein-projekt.de www.mein-projekt.de;
    return 301 https://$host$request_uri;
}

Claude Code kann eine bestehende HTTP-Konfiguration in eine vollständige HTTPS-Konfiguration mit HSTS, OCSP-Stapling und sicheren Cipher-Suites umschreiben — und erklärt jeden Parameter dabei:

claude "Optimiere diese Nginx SSL-Konfiguration auf Sicherheit
und Performance. Füge OCSP-Stapling, HTTP/2, HSTS und einen
A+ Score auf SSL Labs hinzu." < /etc/nginx/sites-available/mein-projekt.conf

5. Load Balancing: upstream, least_conn, ip_hash

Wenn eine einzelne Backend-Instanz nicht mehr ausreicht, verteilt Nginx den Traffic auf mehrere. Die Konfiguration ist überraschend kompakt — der upstream-Block enthält die Backend-Liste, der Rest bleibt gleich:

upstream app_cluster {
    # Standard: Round Robin (gleichmäßige Verteilung)
    server 10.0.0.1:3000;
    server 10.0.0.2:3000;
    server 10.0.0.3:3000;

    # Alternativ: least_conn (immer zur am wenigsten ausgelasteten Instanz)
    # least_conn;

    # Alternativ: ip_hash (gleicher Client immer zur gleichen Instanz — Session-Affinity)
    # ip_hash;

    keepalive 64;
}

server {
    listen 443 ssl http2;
    server_name api.mein-projekt.de;

    location / {
        proxy_pass http://app_cluster;
        # ... proxy_set_header wie oben
    }
}

Welche Load-Balancing-Methode passt wann? Claude Code erklärt das anhand deines konkreten Anwendungsfalls: least_conn eignet sich für Anfragen mit unterschiedlicher Bearbeitungsdauer (z.B. API-Calls), ip_hash ist sinnvoll wenn Sitzungsdaten lokal auf dem Backend gespeichert sind und kein zentrales Session-Store vorhanden ist.

6. Caching: proxy_cache und Cache-Control-Header

Nginx kann Antworten des Backends zwischenspeichern und wiederholen — ohne die Anwendung erneut zu befragen. Für statische oder selten wechselnde Inhalte reduziert das die Backend-Last erheblich.

# In nginx.conf (http-Block)
proxy_cache_path /var/cache/nginx
    levels=1:2
    keys_zone=app_cache:10m
    max_size=1g
    inactive=60m
    use_temp_path=off;

# Im server-Block
location /api/products {
    proxy_pass         http://app_backend;
    proxy_cache        app_cache;
    proxy_cache_valid  200 10m;   # 200er Antworten 10 Minuten cachen
    proxy_cache_valid  404  1m;   # 404er Antworten 1 Minute cachen
    proxy_cache_use_stale error timeout updating http_500 http_502 http_503;
    add_header X-Cache-Status $upstream_cache_status;
}

Der X-Cache-Status-Header zeigt im Browser, ob eine Antwort aus dem Cache kam (HIT) oder frisch vom Backend (MISS) — nützlich beim Debugging. Claude Code kann eine komplette Cache-Strategie für deinen Stack entwerfen und dabei berücksichtigen, welche Endpunkte gecacht werden sollen und welche nicht.

7. Claude Code Nginx-Tipps: Konfiguration generieren, Fehler debuggen, Performance tunen

Hier sind die Einsatzszenarien, die im Alltag am meisten Zeit sparen:

Konfiguration aus Anforderungen generieren

Statt Dokumentation zu lesen und Konfigurationsschnipsel zusammenzusetzen, beschreibst du das Ziel:

claude "Erstelle eine produktionsreife Nginx-Konfiguration für:
- Domain: app.beispiel.de
- Backend: Node.js auf Port 3000
- SSL via Let's Encrypt (Zertifikat liegt bereits vor)
- WebSocket-Unterstützung für /ws
- Statische Dateien aus /var/www/app/public direkt ausliefern
- Rate Limiting: max 100 Requests/Minute pro IP"

Fehler aus dem Error-Log diagnostizieren

claude "Was bedeutet dieser Nginx-Fehler und wie behebe ich ihn?" < /var/log/nginx/error.log

Claude Code liest das Log, identifiziert wiederkehrende Fehlertypen, trennt primäre Fehler von Folgefehlern und gibt konkrete Lösungsschritte. Typische Fehlerklassen die Claude Code zuverlässig diagnostiziert: upstream timed out, connect() failed, no live upstreams, SSL-Handshake-Fehler.

Bestehende Konfiguration optimieren

cat /etc/nginx/sites-available/mein-projekt.conf | claude "Analysiere
diese Nginx-Konfiguration auf Performance-Probleme. Ich möchte
gzip aktivieren, HTTP/2 Push nutzen und die Worker-Prozesse
optimal für einen 8-Core-Server konfigurieren."

Claude Code erkennt fehlende Optimierungen (gzip_comp_level zu hoch, worker_processes nicht auf auto gesetzt, sendfile nicht aktiviert) und schlägt eine überarbeitete Konfiguration vor, die du direkt einsetzen kannst.

• Konfiguration generieren: Ziel beschreiben, fertige Config erhalten — kein Dokumentation-Suchen
• Fehler debuggen: Error-Log übergeben, Ursache und Lösung in Klartext
• Performance tunen: Bestehende Config analysieren lassen, gezielte Verbesserungen anwenden
• Sicherheit prüfen: SSL-Konfiguration, Header-Security, Rate-Limiting auf Lücken prüfen

Zwei verwandte Artikel die dieses Thema ergänzen:

• Claude Code Debugging — Bugs systematisch finden, nicht durch Trial-and-Error
• Claude Code für Unternehmen — Deployment, Zugriffskontrolle und Team-Workflows