Zum Inhalt

Nginx

Dokumenttyp: Developer Playbook
Status: Draft v0.2
Stand: 2026-06-30
Prinzip: Allgemeine Anleitung mit Praxisbeispiel aus Immohai

Ziel

Dieses Dokument erklärt, welche Rolle Nginx auf einem Linux-Server spielt und warum Nginx häufig als zentraler Webserver und Reverse Proxy verwendet wird.

Die konkrete Veröffentlichung von Domains, Subdomains, lokalen Ports und HTTPS wird im Kapitel 06 Veröffentlichung beschrieben.

Kurz erklärt

Nginx ist ein Webserver.

Ein Webserver nimmt Anfragen aus dem Internet entgegen und liefert eine Antwort zurück.

Nginx kann zwei wichtige Aufgaben übernehmen:

  1. Dateien direkt ausliefern.
  2. Anfragen an andere Dienste weiterleiten.

Für moderne Webapps wird Nginx sehr häufig als Reverse Proxy eingesetzt.

Grundprinzip

Ohne Reverse Proxy müsste eine App direkt öffentlich erreichbar sein.

Das ist für kleine Tests möglich, aber für mehrere Apps auf einem Server unpraktisch.

Mit Nginx sieht die Struktur so aus:

Browser
↓
Domain oder Subdomain
↓
Nginx
↓
lokaler Dienst
↓
Docker-Container

Beispiel:

https://immohai.ohaisoft.com
↓
Nginx
↓
http://127.0.0.1:8200
↓
Immohai App

Warum Nginx wichtig ist

Nginx übernimmt eine zentrale Rolle zwischen Internet und Anwendung.

Aufgabe Bedeutung
öffentliche Ports verwalten Nginx belegt 80 und 443
Subdomains unterscheiden jede Domain kann zu einem anderen Dienst führen
lokale Dienste schützen Docker-Container müssen nicht direkt öffentlich sein
HTTPS ermöglichen Certbot kann Nginx automatisch konfigurieren
mehrere Apps betreiben ein Server kann mehrere Projekte ausliefern
Weiterleitungen verwalten HTTP kann auf HTTPS weitergeleitet werden

Typische Einsatzarten

Nginx kann in verschiedenen Rollen verwendet werden.

Einsatzart Beschreibung
Webserver liefert statische Dateien direkt aus
Reverse Proxy leitet Anfragen an interne Dienste weiter
TLS-Termination nimmt HTTPS entgegen und verwaltet Zertifikate
Load Balancer verteilt Anfragen auf mehrere Backend-Dienste
Gateway zentraler Einstiegspunkt für mehrere Apps

Für das Developer Playbook ist vor allem die Rolle als Reverse Proxy wichtig.

Host-Nginx und Nginx im Docker-Container

Es gibt zwei unterschiedliche Arten, wie Nginx in einem Projekt vorkommen kann.

1. Nginx als Host-Service

Nginx läuft direkt auf dem Server.

Er wird über apt installiert:

sudo apt install nginx -y

Dieser Nginx übernimmt die öffentlichen Ports:

80  → HTTP
443 → HTTPS

Er entscheidet, welche Domain zu welchem lokalen Dienst gehört.

Beispiel:

playbook.ohaisoft.com       → 127.0.0.1:8100
immohai.ohaisoft.com        → 127.0.0.1:8200
docs.immohai.ohaisoft.com   → 127.0.0.1:8201

Das ist der zentrale Reverse Proxy.

2. Nginx im Docker-Container

Nginx kann auch innerhalb eines Docker-Containers laufen.

Das ist häufig sinnvoll, wenn ein Container eine einfache statische Website ausliefert.

Beispiel:

services:
  web:
    image: nginx:latest
    container_name: app-web
    ports:
      - "127.0.0.1:8200:80"
    volumes:
      - ./frontend:/usr/share/nginx/html:ro

Dieser Container ist nicht direkt öffentlich erreichbar.

Er läuft nur lokal auf:

127.0.0.1:8200

Der Host-Nginx leitet öffentliche Anfragen dann an diesen lokalen Container weiter.

Empfohlene Architektur

Für kleine und mittlere Webprojekte wird folgende Struktur empfohlen:

Internet
↓
Host-Nginx auf Port 80/443
↓
lokaler Docker-Port
↓
Docker-Container

Der Docker-Container sollte nicht direkt auf 0.0.0.0:80 veröffentlicht werden.

Nicht empfohlen:

ports:
  - "80:80"

Empfohlen:

ports:
  - "127.0.0.1:8200:80"

Dadurch bleibt der Container lokal und Nginx übernimmt die öffentliche Erreichbarkeit.

Installation

Nginx wird auf Ubuntu über apt installiert.

sudo apt update
sudo apt install nginx -y

Status prüfen:

sudo systemctl status nginx

Nginx starten:

sudo systemctl start nginx

Nginx beim Systemstart aktivieren:

sudo systemctl enable nginx

Wichtige Befehle

Befehl Zweck
sudo systemctl status nginx Status prüfen
sudo systemctl start nginx Nginx starten
sudo systemctl stop nginx Nginx stoppen
sudo systemctl restart nginx Nginx vollständig neu starten
sudo systemctl reload nginx Konfiguration neu laden
sudo nginx -t Konfiguration testen
sudo journalctl -u nginx Systemlogs anzeigen

Konfiguration testen

Nach jeder Änderung an Nginx sollte zuerst die Konfiguration geprüft werden:

sudo nginx -t

Erwartung:

syntax is ok
test is successful

Erst danach Nginx neu laden:

sudo systemctl reload nginx

Nicht direkt neu starten, ohne vorher zu testen.

Dateistruktur unter Ubuntu

Unter Ubuntu liegen Nginx-Konfigurationen typischerweise hier:

/etc/nginx/

Wichtige Unterordner:

/etc/nginx/sites-available/
/etc/nginx/sites-enabled/

Bedeutung:

Pfad Bedeutung
/etc/nginx/sites-available/ vorbereitete Konfigurationen
/etc/nginx/sites-enabled/ aktive Konfigurationen
/etc/nginx/nginx.conf globale Hauptkonfiguration
/var/log/nginx/access.log Zugriffslog
/var/log/nginx/error.log Fehlerlog

Sites aktivieren

Eine Konfiguration wird üblicherweise unter sites-available erstellt.

Beispiel:

sudo nano /etc/nginx/sites-available/app.example.com

Danach wird sie nach sites-enabled verlinkt:

sudo ln -s /etc/nginx/sites-available/app.example.com /etc/nginx/sites-enabled/

Danach prüfen:

sudo nginx -t

Und neu laden:

sudo systemctl reload nginx

Einfaches Reverse-Proxy-Beispiel

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

    location / {
        proxy_pass http://127.0.0.1:8200;
        proxy_http_version 1.1;

        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;
    }
}

Bedeutung:

Anweisung Bedeutung
listen 80; Nginx nimmt HTTP-Anfragen an
server_name app.example.com; gilt für diese Domain
location / gilt für alle Pfade unter /
proxy_pass leitet intern an den lokalen Dienst weiter
proxy_set_header Host gibt den ursprünglichen Hostnamen weiter
X-Real-IP gibt die echte Client-IP weiter
X-Forwarded-For gibt Proxy-Kette weiter
X-Forwarded-Proto gibt HTTP/HTTPS-Schema weiter

Praxisbeispiel Immohai

Im Praxisbeispiel läuft Nginx direkt auf dem Server als Host-Service.

Nginx übernimmt die öffentlichen Domains:

playbook.ohaisoft.com
immohai.ohaisoft.com
docs.immohai.ohaisoft.com

Die Docker-Dienste laufen lokal:

127.0.0.1:8100 → Developer Playbook
127.0.0.1:8200 → Immohai App
127.0.0.1:8201 → Immohai Dokumentation

Nginx leitet weiter:

playbook.ohaisoft.com       → 127.0.0.1:8100
immohai.ohaisoft.com        → 127.0.0.1:8200
docs.immohai.ohaisoft.com   → 127.0.0.1:8201

Wichtig:

Immohai verwendet zusätzlich einen Nginx-Container für die statische App-Auslieferung. Dieser Container ist aber nicht direkt öffentlich, sondern nur lokal über den Host-Nginx erreichbar.

Unterschied zur Veröffentlichung

Dieses Kapitel erklärt Nginx als Server-Software.

Die konkrete Veröffentlichung wird im Bereich 06 Veröffentlichung dokumentiert:

setup/06-veroeffentlichung/
├── 00-uebersicht.md
├── 01-domain-und-dns.md
├── 02-port-strategie.md
├── 03-nginx-reverse-proxy.md
├── 04-https-mit-certbot.md
├── 05-app-und-doku-veroeffentlichen.md
└── 06-veroeffentlichung-checkliste.md

Dort wird Schritt für Schritt beschrieben:

  • wie Domains eingerichtet werden,
  • welche lokalen Ports verwendet werden,
  • wie Nginx-Dateien angelegt werden,
  • wie HTTPS mit Certbot aktiviert wird,
  • wie die öffentliche Erreichbarkeit getestet wird.

Typische Fehler

Fehler Ursache Lösung
Nginx startet nicht Port 80 ist bereits belegt sudo ss -ltnp \| grep ':80' ausführen
Änderung wird nicht sichtbar Nginx wurde nicht neu geladen sudo systemctl reload nginx
nginx -t schlägt fehl Syntaxfehler in Konfigurationsdatei Fehlermeldung lesen und Datei korrigieren
Subdomain zeigt falsche App falscher server_name oder proxy_pass Nginx-Dateien prüfen
App ist nicht erreichbar lokaler Docker-Port falsch oder Container läuft nicht docker ps und curl 127.0.0.1:<port> prüfen
Certbot schlägt fehl Nginx oder DNS noch nicht korrekt erst DNS und HTTP prüfen
Container blockiert Port 80 Docker läuft mit 0.0.0.0:80 Container auf lokalen Port umstellen

Best Practices

  • Nginx als zentralen Host-Reverse-Proxy verwenden.
  • Docker-Dienste nur lokal auf 127.0.0.1 binden.
  • Für jede Subdomain eine eigene Datei unter sites-available verwenden.
  • Konfigurationen nur über symbolische Links in sites-enabled aktivieren.
  • Nach jeder Änderung sudo nginx -t ausführen.
  • Erst nach erfolgreichem Test sudo systemctl reload nginx ausführen.
  • Öffentliche Ports 80 und 443 für Nginx freihalten.
  • Nginx-Konfigurationen dokumentieren, aber keine Secrets speichern.
  • Logs bei Fehlern prüfen.

Checkliste

  • [ ] Nginx installiert
  • [ ] Nginx läuft als Systemdienst
  • [ ] Nginx ist beim Systemstart aktiviert
  • [ ] Port 80 ist nicht durch Docker blockiert
  • [ ] Port 443 ist für HTTPS verfügbar
  • [ ] grundlegende Nginx-Dateistruktur verstanden
  • [ ] Reverse-Proxy-Prinzip verstanden
  • [ ] Unterschied zwischen Host-Nginx und Nginx-Container verstanden
  • [ ] sudo nginx -t bekannt
  • [ ] sudo systemctl reload nginx bekannt
  • [ ] Logs bekannt
  • [ ] konkrete Veröffentlichung im Kapitel 06 Veröffentlichung dokumentiert