Docker Nginx vollständiger Leitfaden: Konfigurations-Mounts, HTTPS und Reverse Proxy

Sie drücken zum siebten Mal docker restart nginx, laden die Seite neu – und sehen weiterhin die 502-Fehlerseite. Sie haben nginx.conf geändert, aber die Konfiguration im Container wirkt einfach nicht.

Konfigurationsprobleme beim Docker-Deployment von Nginx kennt fast jeder, der Container einsetzt. Config-Mounts, HTTPS-Zertifikate, Kommunikation zwischen Containern – das klingt einfach, birgt aber viele Fallstricke. Dieser Artikel liefert ein vollständiges, praxistaugliches Setup: von korrekten Mount-Varianten über automatische Zertifikatserneuerung bis zur Netzwerkkonfiguration für Reverse Proxy.

Sie lernen:

• Warum geänderte Konfigurationen nicht greifen – und 5 bewährte Mount-Varianten
• Den vollständigen HTTPS-Pfad von selbstsignierten Zertifikaten bis Let’s Encrypt
• Netzwerk-Tricks beim Reverse Proxy für andere Docker-Container
• Sicherheits-Härtung und Performance-Tuning für die Produktion

Docker Nginx: Grundkonfiguration und Datei-Mounts

Warum Konfigurationsdateien mounten?

Die Frage kommt oft: Kann man Nginx-Config nicht einfach ins Image packen? Geht schon – aber der Aufwand lohnt sich selten.

Jede kleine Änderung bedeutet: Image neu bauen, in die Registry pushen, pullen, Container neu starten – leicht 15 Minuten. Dazu kommen Versionsverwaltung und Multi-Environment-Switching. Um zwei Uhr nachts ein Rollback brauchen und auf den Image-Build warten? Unschön.

Config-Mounts lösen genau das: Datei auf dem Host ändern, im Container sofort wirksam. Testen, Rollback und Teamarbeit werden deutlich einfacher.

Wichtige Verzeichnisse im Nginx-Container

Zuerst die Struktur im Container:

/etc/nginx/
├── nginx.conf              # Hauptkonfiguration
├── conf.d/                 # Unterconfigs, Site-Konfigurationen
│   └── default.conf        # Standard-Site
/usr/share/nginx/html       # Document Root für statische Dateien
/var/log/nginx/             # Log-Verzeichnis
    ├── access.log
    └── error.log

Entscheidend: In nginx.conf steht include /etc/nginx/conf.d/*.conf;. Die Hauptconfig lädt automatisch alle .conf-Dateien aus conf.d. Nur nginx.conf mounten und conf.d vergessen – der erste klassische Fehler.

Korrekte Mount-Variante: Schritt für Schritt

Nicht gleich den Container starten. Eine kurze Vorbereitung spart später viel Ärger.

Schritt 1: Standard-Config aus dem Container als Vorlage kopieren

Warum? Die offizielle Default-Config ist getestet – darauf aufbauen ist zuverlässiger als bei null anfangen.

# Temporären Container starten
docker run --name nginx-temp -d nginx

# Standard-Config exportieren
docker cp nginx-temp:/etc/nginx/nginx.conf ./nginx/nginx.conf
docker cp nginx-temp:/etc/nginx/conf.d ./nginx/conf.d

# Aufräumen
docker stop nginx-temp && docker rm nginx-temp

Schritt 2: Standard-Verzeichnisstruktur auf dem Host anlegen

Ich lege Docker-Dateien unter /opt ab – Sie können den Pfad anpassen:

mkdir -p /opt/nginx/{conf,conf.d,html,logs,ssl}

Diese Struktur deckt Config, statische Dateien, Logs und SSL-Zertifikate ab.

Schritt 3: Container starten und alle Verzeichnisse mounten

Auf die Pfadzuordnung bei jedem -v achten:

docker run -d --name my-nginx \
  -p 80:80 -p 443:443 \
  -v /opt/nginx/conf/nginx.conf:/etc/nginx/nginx.conf:ro \
  -v /opt/nginx/conf.d:/etc/nginx/conf.d \
  -v /opt/nginx/html:/usr/share/nginx/html \
  -v /opt/nginx/logs:/var/log/nginx \
  -v /opt/nginx/ssl:/etc/nginx/ssl \
  nginx

Wichtige Punkte:

• -p 80:80 -p 443:443: HTTP und HTTPS (für HTTPS später nötig)
• :ro bei nginx.conf – Schreibschutz gegen versehentliche Änderungen im Container
• conf.d als ganzes Verzeichnis mounten, nicht als Einzeldatei (Grund gleich unten)

Vier typische Fallen

Falle 1: Nach vim-Bearbeitung synchronisiert der Container nicht

Klassiker: nginx.conf auf dem Host geändert, Container neu gestartet – keine Wirkung.

Ursache: vim erzeugt beim Speichern oft eine neue Datei mit neuem inode. Docker bindet über den inode – ändert sich der, zeigt der Container weiter die alte Datei.

Zwei Lösungen:

• Option A: nano nutzen (inode bleibt gleich)
• Option B: ganzes Verzeichnis statt Einzeldatei mounten

Ich nutze Option B. Beim Verzeichnis-Mount ist der inode egal; Configs lassen sich flexibel hinzufügen und entfernen.

Falle 2: Falscher include-Pfad

Im Container prüfen:

docker exec -it my-nginx bash
cat /etc/nginx/nginx.conf | grep include

Diese Zeile muss existieren:

include /etc/nginx/conf.d/*.conf;

Wenn Sie /opt/nginx/conf.d/*.conf (Host-Pfad) eintragen, ist das falsch. Im Container gelten nur Container-Pfade.

Falle 3: conf.d nicht gemountet

Alibaba Cloud - Top-Wahl für Entwickler, exklusiv 15 % Rabatt auf Lighthouse-Server

15 % Rabatt sichern →Anzeige

Nur nginx.conf reicht nicht. Neue Site-Configs unter conf.d auf dem Host sind im Container unsichtbar.

Prüfen:

docker exec my-nginx ls /etc/nginx/conf.d

Es sollten alle Dateien aus /opt/nginx/conf.d sichtbar sein.

Falle 4: Dateiberechtigungen blockieren Nginx

Unter Linux häufig: Config zu restriktiv, Nginx-Prozess (User nginx) kann nicht lesen.

Lösung:

chmod 644 /opt/nginx/conf/nginx.conf
chmod 644 /opt/nginx/conf.d/*.conf

Nach Änderungen Syntax testen:

docker exec my-nginx nginx -t

Bei syntax is ok passt es.

Einzeldatei vs. Verzeichnis-Mount: Was wählen?

nginx.conf (Hauptconfig): Einzeldatei + :ro – selten geändert

conf.d: immer Verzeichnis-Mount – flexibel für neue Sites

html, logs: Verzeichnis-Mount

Faustregel: Mehrere Dateien flexibel verwalten → Verzeichnis. Kernconfig mit Versionskontrolle → Einzeldatei mit Schreibschutz.

HTTPS und Let’s Encrypt Auto-Renewal

Selbstsigniertes Zertifikat: Schnelltest in der Entwicklung

In Produktion brauchen Sie echte Zertifikate; für Dev/Test reicht selbstsigniert:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /opt/nginx/ssl/nginx.key \
  -out /opt/nginx/ssl/nginx.crt \
  -subj "/C=CN/ST=Beijing/L=Beijing/O=Dev/CN=localhost"

Erzeugt zwei Dateien:

• nginx.key: privater Schlüssel – niemals preisgeben
• nginx.crt: Zertifikat

In /opt/nginx/conf.d/ eine ssl.conf anlegen:

server {
    listen 443 ssl;
    server_name localhost;

    ssl_certificate /etc/nginx/ssl/nginx.crt;
    ssl_certificate_key /etc/nginx/ssl/nginx.key;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location / {
        root /usr/share/nginx/html;
        index index.html;
    }
}

Wichtig:

• ssl_certificate-Pfade sind Container-Pfade (/etc/nginx/ssl), nicht /opt/nginx/ssl auf dem Host
• Nur TLS 1.2 und 1.3 – ältere Protokolle sind unsicher
• -p 443:443 nicht vergessen

Config hot-reloaden:

docker exec my-nginx nginx -s reload

Unter https://localhost warnt der Browser vor nicht vertrauenswürdigem Zertifikat – normal bei selbstsigniert. Einfach fortfahren.

Let’s Encrypt: Kostenlose Zertifikate für Produktion

Let’s Encrypt ist praktisch: kostenlos, automatisiert, global vertrauenswürdig. Nachteil: 90 Tage Laufzeit – mit Auto-Renewal kein Problem.

Empfehlung: docker-compose + certbot-Container – deutlich zuverlässiger als manuelles Setup.

Vollständige docker-compose.yml:

version: '3'

services:
  nginx:
    image: nginx:latest
    container_name: my-nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d
      - ./nginx/html:/usr/share/nginx/html
      - ./certbot/conf:/etc/letsencrypt
      - ./certbot/www:/var/www/certbot
    command: "/bin/sh -c 'while :; do sleep 6h & wait $${!}; nginx -s reload; done & nginx -g \"daemon off;\"'"
    networks:
      - web

  certbot:
    image: certbot/certbot
    container_name: certbot
    volumes:
      - ./certbot/conf:/etc/letsencrypt
      - ./certbot/www:/var/www/certbot
    entrypoint: "/bin/sh -c 'trap exit TERM; while :; do certbot renew; sleep 12h & wait $${!}; done;'"
    networks:
      - web

networks:
  web:
    driver: bridge

Kernpunkte:

1. Geteilte Mounts für Zertifikate und Validierung

• ./certbot/conf in beiden Containern – certbot erzeugt, nginx liest
• ./certbot/www für HTTP-Validierung (webroot)

2. Nginx reload alle 6 Stunden

Hintergrund-Loop: alle 6 Stunden reload – erneuerte Zertifikate greifen sofort.

3. Certbot prüft alle 12 Stunden

Let’s Encrypt empfiehlt tägliche Prüfung; 12 Stunden ist sicherer.

Erstmalige Zertifikatsanforderung

In /opt/nginx/conf.d/ zuerst temp.conf für HTTP-Validierung:

server {
    listen 80;
    server_name your-domain.com;  # Ihre Domain

    location /.well-known/acme-challenge/ {
        root /var/www/certbot;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

Services starten:

docker-compose up -d

Zertifikat anfordern (Domain und E-Mail anpassen):

docker-compose run --rm certbot certonly --webroot \
  -w /var/www/certbot \
  -d your-domain.com \
  --email [email protected] \
  --agree-tos \
  --no-eff-email

Bei Erfolg erscheint „Congratulations!”. Zertifikate liegen unter ./certbot/conf/live/your-domain.com/.

Jetzt die finale HTTPS-Config – temp.conf anpassen:

server {
    listen 80;
    server_name your-domain.com;

    location /.well-known/acme-challenge/ {
        root /var/www/certbot;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    # SSL-Optimierung
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256';
    ssl_prefer_server_ciphers on;

    # HSTS (HTTPS erzwingen)
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    location / {
        root /usr/share/nginx/html;
        index index.html;
    }
}

Reload:

docker-compose exec nginx nginx -s reload

Auto-Renewal prüfen

Let’s-Encrypt-Zertifikate gelten 90 Tage; certbot erneuert ab 30 Tagen Restlaufzeit. Manuell testen:

docker-compose run --rm certbot renew --dry-run

Bei „The dry run was successful” passt alles.

Logs prüfen:

docker-compose logs certbot

Zusätzliche SSL-Sicherheit

Optional für strengere SSL-Konfiguration:

# OCSP Stapling
ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/letsencrypt/live/your-domain.com/chain.pem;
resolver 8.8.8.8 8.8.4.4 valid=300s;
resolver_timeout 5s;

# iframe-Einbettung verbieten (Clickjacking-Schutz)
add_header X-Frame-Options DENY;

# XSS-Schutz
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";

Anschließend auf SSL Labs testen – A+ ist erreichbar.

Reverse Proxy und Docker-Container-Kommunikation

Netzwerk-Grundlagen

Nginx als Reverse Proxy für andere Container – am meisten Ärgernis macht das Netzwerk. Container-IP direkt nutzen? Nach Neustart ändert sich die IP, Config muss angepasst werden.

Zwei häufige Modi:

• bridge: Standard, Container kommunizieren über virtuelle Bridge
• host: Host-Netzwerkstack, performant, wenig Isolation

Für Reverse Proxy empfehle ich ein eigenes Bridge-Netzwerk:

KiloClaw - Managed OpenClaw für Unternehmen: AI-Agent-Orchestrierung und smartes Modell-Routing

Jetzt starten →Anzeige

1. Kommunikation über Servicenamen statt IP
2. Netzwerk-Isolation pro Projekt
3. Automatische DNS-Auflösung durch Docker

Eigenes Netzwerk anlegen und Container starten

Netzwerk erstellen:

docker network create my-app-network

Backend starten (z. B. Node.js-API):

docker run -d \
  --name backend-api \
  --network my-app-network \
  -e NODE_ENV=production \
  my-backend:latest

Nginx im gleichen Netzwerk:

docker run -d \
  --name my-nginx \
  --network my-app-network \
  -p 80:80 -p 443:443 \
  -v /opt/nginx/conf.d:/etc/nginx/conf.d \
  nginx

Im gleichen Netzwerk erreichen Sie das Backend unter dem Namen backend-api.

Reverse-Proxy-Konfiguration in der Praxis

In /opt/nginx/conf.d/ api-proxy.conf anlegen:

upstream backend {
    server backend-api:3000;  # Containername:Port
    keepalive 32;
}

server {
    listen 80;
    server_name api.example.com;

    # API-Proxy
    location /api/ {
        proxy_pass http://backend/;

        # Echte Client-Informationen 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 (falls nötig)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

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

    # Statische Dateien direkt durch Nginx
    location / {
        root /usr/share/nginx/html;
        index index.html;
        try_files $uri $uri/ /index.html;
    }
}

Leicht übersehene Details:

1. upstream und proxy_pass – Pfadbehandlung

proxy_pass http://backend/; mit abschließendem Slash: /api/users wird zu http://backend/users (Präfix /api entfernt).

Ohne Slash: http://backend/api/users (voller Pfad bleibt).

2. X-Forwarded-For

Backend braucht diesen Header für die echte Client-IP – sonst sieht es nur die Nginx-Container-IP.

3. keepalive-Pool

keepalive 32 im upstream spart TCP-Handshakes – wichtig bei hoher Last.

Multi-Container mit docker-compose vereinfachen

Netzwerk und Container einzeln starten ist mühsam – docker-compose in einem Schritt:

version: '3.8'

services:
  backend:
    image: my-backend:latest
    container_name: backend-api
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgres://db:5432/mydb
    networks:
      - app-network
    depends_on:
      - db

  nginx:
    image: nginx:latest
    container_name: my-nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d
      - ./nginx/html:/usr/share/nginx/html
      - ./nginx/logs:/var/log/nginx
    networks:
      - app-network
    depends_on:
      - backend

  db:
    image: postgres:14
    container_name: postgres-db
    environment:
      - POSTGRES_PASSWORD=secret
      - POSTGRES_DB=mydb
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

volumes:
  db-data:

Gesamten Stack starten:

docker-compose up -d

Docker erledigt automatisch:

• Netzwerk app-network anlegen
• Startreihenfolge per depends_on
• DNS zwischen Containern

In der Nginx-Config reichen backend und db als Hostnamen.

Typische Proxy-Probleme debuggen

Problem 1: 502 Bad Gateway

Häufigste Ursachen:

• Backend nicht gestartet oder abgestürzt
• Nginx und Backend in unterschiedlichen Netzwerken
• Falscher Backend-Port

Debug-Schritte:

# Backend prüfen
docker ps | grep backend

# Netzwerk prüfen
docker network inspect my-app-network

# Aus Nginx-Container testen
docker exec -it my-nginx sh
ping backend-api
curl http://backend-api:3000/health

Kein ping → Netzwerkproblem. curl-Timeout → Backend lauscht falsch.

Problem 2: Request-Timeout

Standard-Proxy-Timeout: 60 Sekunden. Bei langen API-Läufen (Uploads, schwere Berechnungen) erhöhen:

location /api/long-running/ {
    proxy_pass http://backend/;
    proxy_connect_timeout 300s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;
}

Problem 3: POST-Body geht verloren

Manchmal wird POST zu GET oder Body ist leer:

location /api/ {
    proxy_pass http://backend/;
    proxy_request_buffering off;  # Request-Buffering deaktivieren
    client_max_body_size 100M;     # Große Uploads erlauben
}

Load Balancing für mehrere Backends

Mehrere Backend-Instanzen – Nginx verteilt die Last:

upstream backend_cluster {
    least_conn;  # Wenigste Verbindungen

    server backend-1:3000 weight=3;
    server backend-2:3000 weight=1;
    server backend-3:3000 backup;     # Backup-Server

    keepalive 32;
}

server {
    listen 80;

    location /api/ {
        proxy_pass http://backend_cluster/;
        # ... weitere proxy-Einstellungen
    }
}

Algorithmen:

• round-robin (Standard): Round-Robin
• least_conn: wenigste aktive Verbindungen
• ip_hash: gleiche Client-IP → gleicher Server

Fällt ein Backend aus, leitet Nginx auf gesunde Knoten um.

Produktions-Best Practices und Performance

Konfigurationsverwaltung: Nicht ungeschützt live gehen

Configs lose auf dem Server ablegen – okay für Dev. In Produktion braucht es Struktur.

Git für Configs

Separates Repo für alle Nginx-Configs, Umgebungen in Unterverzeichnissen:

• Versionshistorie, Rollback per git checkout
• Team-Review per Pull Request
• CI/CD-Integration

Config-Templates

Umgebungen ähneln sich – Templates mit Variablen sparen Arbeit. Deployment mit envsubst.

Log-Management: Bevor die Festplatte voll ist

Nginx-Logs wachsen schnell – bei hohem Traffic mehrere GB pro Tag. Ohne Rotation: Festplatte voll, Container down.

Log-Rotation

logrotate auf dem Host: täglich rotieren, 14 Tage behalten, alte Logs komprimieren. Nach Rotation nginx -s reopen, sonst schreibt Nginx weiter in die alte Datei.

Zentralisierte Logs

🔥 Verschwende keine Monate für ungenutzte Produkte! Teste deine SaaS-Nutzenversprechen mit Adsterra bei kleinem Budget →

Jetzt testen →Anzeige

Bei mehreren Servern: ELK, Loki oder Cloud-Dienste. Docker-Log-Treiber oder Promtail eignen sich gut.

Graceful Reload: Nutzer merken nichts

Nach Config-Änderung nicht docker restart. Neustart bricht alle Verbindungen ab.

Richtig:

# Syntax prüfen
docker exec my-nginx nginx -t

# Dann reload
docker exec my-nginx nginx -s reload

reload ist graceful: neue Worker mit neuer Config, alte Worker beenden laufende Requests – nahtloser Wechsel.

Sicherheits-Checkliste vor Go-Live

1. Nginx-Version verbergen

Standard-Fehlerseiten zeigen die Version – Angriffsfläche für bekannte CVEs. In http-Block: server_tokens off;

2. Rate Limiting gegen DDoS

http {
    # Anfragen pro IP begrenzen
    limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

    # Gleichzeitige Verbindungen begrenzen
    limit_conn_zone $binary_remote_addr zone=conn_limit:10m;
}

server {
    location /api/ {
        limit_req zone=api_limit burst=20 nodelay;
        limit_conn conn_limit 10;
        proxy_pass http://backend/;
    }
}

3. Config schreibgeschützt mounten

Hauptconfig mit :ro.

4. Least Privilege

In nginx.conf user nginx; – nicht root, sonst großes Sicherheitsrisiko.

Performance-Tuning

Worker-Prozesse

worker_processes auto;  # An CPU-Kerne anpassen
worker_cpu_affinity auto;  # CPU-Affinität

auto passt Worker an verfügbare Kerne an.

Verbindungslimits

events {
    worker_connections 2048;  # Max. Verbindungen pro Worker
    use epoll;                # Unter Linux am performantesten
}

Theoretisches Maximum: worker_processes * worker_connections. Praktisch auch ulimit -n beachten.

gzip-Kompression

Textinhalte oft 60–80 % kleiner:

http {
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;  # Level 1–9, 6 ist guter Kompromiss
    gzip_types
        text/plain
        text/css
        text/xml
        application/json
        application/javascript
        application/xml+rss
        application/atom+xml
        image/svg+xml;
    gzip_min_length 1000;  # Unter 1 KB nicht komprimieren
}

Caching statischer Assets

location ~* \.(jpg|jpeg|png|gif|ico|css|js|woff2)$ {
    expires 30d;
    add_header Cache-Control "public, immutable";
}

HTTP/2

server {
    listen 443 ssl http2;
    # ... weitere Config
}

Voraussetzung: HTTPS – HTTP/2 erfordert TLS.

Monitoring und Healthchecks

Nicht ohne Monitoring live gehen. Empfehlung: Prometheus + Grafana mit nginx-prometheus-exporter. stub_status in Nginx aktivieren, Zugriff auf Docker-internes Netz beschränken, Metriken scrapen, Dashboard in Grafana.

Fazit

Vier Kernthemen:

Config-Mounts: Verzeichnis statt Einzeldatei, Hauptconfig schreibgeschützt, conf.d und ssl nicht vergessen, vim-Inode-Falle vermeiden.

HTTPS: Dev mit selbstsigniert, Produktion mit Let’s Encrypt + Certbot. docker-compose macht Renewal nahezu wartungsfrei.

Reverse Proxy: Eigenes Bridge-Netzwerk, Kommunikation über Container-/Servicenamen, keepalive im upstream für Performance und Stabilität.

Produktion: Git für Config-Versionen, Log-Rotation, graceful reload statt restart, Sicherheitsmaßnahmen nicht auslassen.

Docker Nginx wirkt simpel, steckt aber voller Details. Wer das verstanden hat, baut eine stabile Web-Architektur von der Entwicklung bis zur Produktion.

Wenn dieser Artikel Ihnen Fallstricke erspart oder ein altes Problem gelöst hat, hat er seinen Zweck erfüllt. Probieren Sie es aus – bei Fragen gerne im Kommentar melden.

Praktischer Tipp: Config-Vorlagen aus diesem Artikel speichern und wiederverwenden. Das Rad muss nicht zweimal erfunden werden.