Was bauen wir?

Am Ende läuft Traefik v3 als zentraler Einstiegspunkt auf deinem Server. Es lauscht auf Port 80/443, erkennt neue Container automatisch über Docker-Labels, leitet HTTP automatisch auf HTTPS um und besorgt für jede Domain ein gültiges Let’s-Encrypt-Zertifikat. Als erste App hängen wir whoami hinter den Proxy – ein winziger Testdienst, der zeigt, dass Routing und TLS greifen. Ein abgesichertes Dashboard gibt es obendrauf.

Das Muster aus diesem Tutorial – ein gemeinsames proxy-Netzwerk plus ein paar Labels – wiederholt sich danach in jedem App-Rezept.

Eine Anfrage durchläuft in Traefik immer dieselben vier Stationen – dieses Vokabular hilft dir beim Debuggen:

1. Entrypoint – der Port, auf dem die Anfrage ankommt (web = 80, websecure = 443).
2. Router – entscheidet anhand einer Regel (meist Host(...)), ob diese Anfrage zu einer App gehört.
3. Middleware (optional) – verändert die Anfrage unterwegs (z. B. HTTPS-Redirect, Basic-Auth, Security-Header).
4. Service – der Container, der am Ende antwortet.

Merksatz zum Debuggen: „Entrypoint → Router → Middleware → Service". Landet eine Anfrage im Nichts, ist fast immer der Router (falsche Domain) oder das Netzwerk (Service nicht erreichbar) schuld.

Voraussetzungen

• Docker + Compose installiert und die Compose-Grundlagen verstanden
• Eine mit dem Server verbundene Domain: DEINE_DOMAIN und die Subdomains müssen per A/AAAA auf den Server auflösen
• Port 80 und 443 sind aus dem Internet erreichbar – Let’s Encrypt prüft darüber, dass dir die Domain gehört. Firewalls entsprechend öffnen (siehe Firewall mit UFW einrichten).

Schritt für Schritt

Schritt 1: Das gemeinsame proxy-Netzwerk anlegen

Traefik und alle Apps müssen sich ein Docker-Netzwerk teilen, damit Traefik die Container erreicht. Wir legen es einmalig und explizit an, damit spätere Stacks einfach andocken können:

docker network create proxy

Prüfe:

docker network ls | grep proxy

c442da869c47   proxy     bridge    local

Dieses Netzwerk ist von den einzelnen Compose-Projekten unabhängig – deshalb binden wir es später als external ein.

Schritt 2: Traefik-Projekt anlegen

Lege einen eigenen Ordner für Traefik an und darin die Datei, in der die Zertifikate gespeichert werden:

mkdir -p ~/traefik && cd ~/traefik
touch acme.json
chmod 600 acme.json

Schritt 3: Die Traefik-compose.yaml

Jetzt die zentrale Konfiguration. Sie ist lang, aber jede Zeile hat einen Zweck – die Erklärung folgt direkt darunter:

services:
  traefik:
    image: traefik:v3.7
    command:
      # Dashboard (in Schritt 7 abgesichert)
      - "--api.dashboard=true"
      # Docker als Quelle; nur Container mit traefik.enable=true
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.docker.network=proxy"
      # Einstiegspunkte: 80 (HTTP) und 443 (HTTPS)
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      # Alles von HTTP automatisch auf HTTPS umleiten
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      # Let's-Encrypt-Resolver namens "le" via HTTP-Challenge
      - "--certificatesresolvers.le.acme.email=DEINE_MAIL"
      - "--certificatesresolvers.le.acme.storage=/acme.json"
      - "--certificatesresolvers.le.acme.httpchallenge=true"
      - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./acme.json:/acme.json
    networks:
      - proxy
    restart: unless-stopped

networks:
  proxy:
    external: true

Die wichtigsten Blöcke:

• providers.docker + exposedbydefault=false: Traefik beobachtet den Docker-Socket, aber nur Container, die ausdrücklich traefik.enable=true tragen. Kein Dienst wird versehentlich öffentlich.
• providers.docker.network=proxy: sagt Traefik, über welches Netzwerk es die Container anspricht – wichtig, wenn Container in mehreren Netzen hängen.
• entrypoints web/websecure: die Ports 80 und 443. Die beiden redirections-Zeilen schicken jeden HTTP-Aufruf automatisch nach HTTPS.
• certificatesresolvers.le: der Let’s-Encrypt-Resolver. Über die HTTP-Challenge weist Traefik Let’s Encrypt nach, dass die Domain auf diesen Server zeigt, und legt das Zertifikat in acme.json ab. Dafür muss Port 80 von außen erreichbar bleiben – auch wenn deine App nur über HTTPS läuft, denn die Challenge kommt über HTTP. Die acme.email nutzt Let’s Encrypt ausschließlich für Warnungen zu ablaufenden Zertifikaten; trag eine echte Adresse ein.
• Der Docker-Socket ist read-only (:ro) eingebunden – Traefik muss ihn lesen, aber nicht beschreiben.

Starte Traefik:

docker compose up -d
docker compose logs -f traefik

In den Logs darf kein ERR zu ACME oder zum Provider stehen. Strg+C beendet nur das Mitlesen, nicht den Container.

Schritt 4: Die erste App hinter Traefik (whoami)

whoami ist ein winziger Dienst, der die empfangene Anfrage zurückgibt – perfekt zum Testen. Eigener Ordner, eigene compose.yaml:

mkdir -p ~/whoami && cd ~/whoami

services:
  whoami:
    image: traefik/whoami:v1.11
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami.rule=Host(`whoami.DEINE_DOMAIN`)"
      - "traefik.http.routers.whoami.entrypoints=websecure"
      - "traefik.http.routers.whoami.tls.certresolver=le"
    networks:
      - proxy
    restart: unless-stopped

networks:
  proxy:
    external: true

Das sind die vier Labels, die du ab jetzt immer wieder brauchst:

• traefik.enable=true – nur dann fasst Traefik den Container an.
• ...routers.whoami.rule=Host(...) – bei welcher Domain dieser Container antwortet. whoami ist ein frei wählbarer Router-Name (pro Container eindeutig).
• ...entrypoints=websecure – über HTTPS (443) erreichbar.
• ...tls.certresolver=le – hol das Zertifikat über den in Schritt 3 definierten Resolver le.

Wichtig: Der Dienst hat kein ports: – er ist nur über Traefik erreichbar, nicht direkt von außen. Und er hängt im proxy-Netzwerk, sonst findet Traefik ihn nicht.

Lege vorher den DNS-Record whoami.DEINE_DOMAIN an (A/AAAA auf die Server-IP, wie im DNS-Tutorial), dann:

docker compose up -d

Rufe https://whoami.DEINE_DOMAIN im Browser auf. Beim ersten Aufruf braucht die Zertifikatsausstellung ein paar Sekunden; danach siehst du ein gültiges Schloss-Symbol und eine Textausgabe wie:

Hostname: bfa4b8dee3d0
IP: 127.0.0.1
IP: 172.19.0.3
RemoteAddr: 172.19.0.2:49734
GET / HTTP/1.1
Host: whoami.DEINE_DOMAIN

Die Zeile Host: bestätigt, dass Traefik anhand der Domain korrekt an diesen Container geroutet hat. Genau dieses Verhalten – Anfrage für whoami.DEINE_DOMAIN landet beim whoami-Container, eine fremde Domain bekommt 404 – ist das Herz des Reverse Proxys.

Prüfe, welche CA das Zertifikat ausgestellt hat. Das trennt „HTTPS läuft" von „ich sehe nur Traefiks Notfall-Zertifikat":

echo | openssl s_client -connect whoami.DEINE_DOMAIN:443 -servername whoami.DEINE_DOMAIN 2>/dev/null | openssl x509 -noout -issuer

Solange du (wie in Schritt 3 empfohlen) den Staging-Server nutzt, steht dort ein Test-Aussteller – der Browser zeigt das Zertifikat noch als unsicher an:

issuer=C=US, O=Let's Encrypt, CN=(STAGING) Ersatz Emmer YR2

Kommt hier TRAEFIK DEFAULT CERT, hat der Resolver kein Zertifikat geholt – dann zur Fehlersuche unten. Steht ein Let’s-Encrypt-Aussteller da, funktioniert die komplette Kette.

Schritt 5: Auf das echte Zertifikat umschalten

Sobald Staging sauber läuft, holst du das richtige, im Browser gültige Zertifikat. Entferne die caserver-Zeile aus dem traefik-Service (Schritt 3), leere die Staging-Zertifikate und starte Traefik neu:

> acme.json                 # verwirft die Staging-Zertifikate (chmod 600 bleibt)
docker compose up -d

Beim nächsten Aufruf holt Traefik ein frisches Produktiv-Zertifikat. In der issuer-Zeile von oben verschwindet danach das (STAGING), und der Browser zeigt ein gültiges Schloss.

Schritt 6: Der HTTP-nach-HTTPS-Redirect

Den hast du in Schritt 3 schon global aktiviert (die zwei redirections-Zeilen). Test:

curl -sI http://whoami.DEINE_DOMAIN | grep -iE 'HTTP/|location'

HTTP/1.1 308 Permanent Redirect
location: https://whoami.DEINE_DOMAIN/

Jeder unverschlüsselte Aufruf wird also automatisch auf HTTPS umgeleitet – du musst in keiner App mehr daran denken.

Schritt 7: Das Dashboard absichern

Traefik bringt ein Dashboard mit, das zeigt, welche Router und Services aktiv sind. Es nie ungeschützt ins Internet stellen. Wir sichern es mit Basic-Auth und hängen es an eine eigene Subdomain. Erzeuge zuerst einen Benutzer:

sudo apt install -y apache2-utils
htpasswd -nbB admin DEIN_PASSWORT

Die Ausgabe (admin:$2y$05$...) kommt in die Labels. In der compose.yaml jedes $ verdoppeln ($$), sonst interpretiert Compose es als Variable. Ergänze im traefik-Service:

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.dashboard.rule=Host(`traefik.DEINE_DOMAIN`)"
      - "traefik.http.routers.dashboard.entrypoints=websecure"
      - "traefik.http.routers.dashboard.tls.certresolver=le"
      - "traefik.http.routers.dashboard.service=api@internal"
      - "traefik.http.routers.dashboard.middlewares=dashboard-auth"
      - "traefik.http.middlewares.dashboard-auth.basicauth.users=admin:$$2y$$05$$..."

Nach docker compose up -d erreichst du das Dashboard unter https://traefik.DEINE_DOMAIN – nach Passwortabfrage.

Im Dashboard siehst du unter HTTP → Routers jeden erkannten Router (mit seiner Host(...)-Regel), unter Services die dahinterliegenden Container und unter Middlewares deine Bausteine wie dashboard-auth. Ein Router wird grün, wenn Regel, Service und – bei websecure – das Zertifikat stimmen; rot heißt, dass etwas fehlt (meist Netzwerk oder Host-Regel). Damit ist das Dashboard dein erster Blick bei „warum antwortet meine App nicht?".

Unter HTTP Routers siehst du jeden Router einzeln – mit seiner Host(...)-Regel, dem Entrypoint, dem TLS-Status (Schloss) und dem Provider docker. So prüfst du auf einen Blick, ob deine Labels korrekt erkannt wurden:

Schritt 8: Sicherheits-Header als wiederverwendbare Middleware

Eine Middleware hängt sich zwischen Router und Service und verändert die Anfrage oder Antwort. Ein Set an Sicherheits-Headern gehört auf jede öffentliche App – einmal definiert, überall angehängt. Definiere die Middleware an einem beliebigen Container (üblich: bei Traefik selbst) über Labels:

      - "traefik.http.middlewares.sec-headers.headers.stsSeconds=31536000"
      - "traefik.http.middlewares.sec-headers.headers.stsIncludeSubdomains=true"
      - "traefik.http.middlewares.sec-headers.headers.frameDeny=true"
      - "traefik.http.middlewares.sec-headers.headers.contentTypeNosniff=true"
      - "traefik.http.middlewares.sec-headers.headers.browserXssFilter=true"

Was die wichtigsten bewirken:

• stsSeconds (HSTS) – der Browser spricht die Domain künftig nur noch über HTTPS an. Ein Jahr (31536000) ist der übliche Wert.
• frameDeny – verbietet das Einbetten in fremde <iframe>s (Clickjacking-Schutz).
• contentTypeNosniff – der Browser rät den Content-Type nicht, sondern nimmt den gelieferten – schließt eine ganze Klasse von Angriffen aus.

Anhängen an eine App per Label (Router-Name anpassen):

      - "traefik.http.routers.whoami.middlewares=sec-headers"

Mehrere Middlewares werden komma-getrennt angegeben (sec-headers,dashboard-auth) und in dieser Reihenfolge durchlaufen. So baust du dir nach und nach einen Baukasten (Auth, Rate-Limiting, IP-Whitelist), den jede App wiederverwenden kann.

Soll ein Header-Set für alle Apps gelten, hängst du die Middleware nicht an jeden Router einzeln, sondern global an den Entrypoint – eine Zeile im command-Block von Traefik:

      - "--entrypoints.websecure.http.middlewares=sec-headers@docker"

Der Zusatz @docker sagt Traefik, dass die Middleware aus dem Docker-Provider stammt (dort hast du sie per Label definiert).

Schritt 9: Das Rezept für jede weitere App

Ab jetzt ist jede App dasselbe Muster – du brauchst Traefik nie wieder anzufassen. Eine neue Anwendung bekommt einen eigenen Ordner mit einer compose.yaml, hängt im proxy-Netzwerk und trägt genau diese Labels (Router-Name und Domain anpassen, bei einem Port ≠ 80 zusätzlich das loadbalancer-Label):

services:
  meineapp:
    image: DEIN_IMAGE:TAG
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.meineapp.rule=Host(`app.DEINE_DOMAIN`)"
      - "traefik.http.routers.meineapp.entrypoints=websecure"
      - "traefik.http.routers.meineapp.tls.certresolver=le"
      # nur nötig, wenn die App NICHT auf Port 80 lauscht:
      - "traefik.http.services.meineapp.loadbalancer.server.port=DEIN_PORT"
    networks:
      - proxy
    restart: unless-stopped

networks:
  proxy:
    external: true

docker compose up -d, DNS-Record auf die Server-IP setzen, fertig – Domain und HTTPS entstehen automatisch. Genau so hängt die erste echte App (Uptime Kuma) hinter den Proxy.

Wenn es nicht funktioniert

Symptom: Im Browser „Zertifikat ungültig" oder Traefik-Log zeigt ACME-Fehler.

Ursache & Lösung: Die drei üblichen Gründe: (1) Der DNS-Record zeigt noch nicht auf den Server – dig +short DEINE_DOMAIN prüfen. (2) Port 80 ist von außen nicht erreichbar (Firewall/netcup-Firewall) – die HTTP-Challenge braucht ihn. (3) Du hast das Rate-Limit der Produktiv-CA gerissen – auf den Staging-Server wechseln (Tipp in Schritt 3), testen, dann zurück.

Symptom: 404 page not found beim Aufruf der App-Domain.

Ursache & Lösung: Traefik kennt die Route nicht. Prüfe: Hat der Container traefik.enable=true? Hängt er im proxy-Netzwerk? Stimmt die Domain in der Host(...)-Regel exakt (inkl. Subdomain)? Das Dashboard (Schritt 7) zeigt unter „HTTP Routers", ob der Router registriert wurde.

Symptom: Der Browser zeigt Traefiks selbstsigniertes Notfall-Zertifikat; im Log steht permissions 644 for /acme.json are too open, please use 600.

Ursache & Lösung: Traefik läuft, hat aber den ACME-Resolver übersprungen – daher kein echtes Zertifikat. chmod 600 acme.json nachholen (Schritt 2) und Container neu starten.

Symptom: Keine App wird geroutet; im Traefik-Log wiederholt sich client version 1.24 is too old. Minimum supported API version is 1.40.

Ursache & Lösung: Deine Traefik-Version ist zu alt für deine Docker-Engine – der Docker-Provider kann den Socket nicht mehr abfragen. Aktuelles Docker (Engine 29, API-Level ≥ 1.40) braucht Traefik ≥ v3.5; deshalb nutzt dieses Tutorial traefik:v3.7. Ältere Tags wie v3.3 funktionieren mit neuem Docker nicht mehr – Image-Tag hochziehen und docker compose up -d erneut ausführen.

Symptom: Basic-Auth am Dashboard wird sofort wieder abgewiesen / Router fehlt.

Ursache & Lösung: In der compose.yaml müssen die $-Zeichen des Hashes verdoppelt sein ($$). Prüfe den Hash außerhalb noch einmal mit htpasswd -nbB.

Symptom: Gateway Timeout oder Traefik erreicht den Container nicht.

Ursache & Lösung: Meist hängt die App im falschen Netzwerk oder Traefik weiß nicht, welches gemeint ist. providers.docker.network=proxy in Traefik und networks: [proxy] an der App müssen zusammenpassen.

Symptom: 502 Bad Gateway, obwohl der Container läuft.

Ursache & Lösung: Traefik erreicht den Container, trifft aber den falschen Port. Lauscht die App nicht auf 80, braucht sie das Label traefik.http.services.<name>.loadbalancer.server.port=<echter-port>. Genau dieser Fall begegnet dir bei der ersten App im nächsten Tutorial (Uptime Kuma auf 3001).

Wartung & Backups

• Sichern musst du acme.json und alle compose.yaml. Damit ist Traefik nach einem Crash in Minuten wiederhergestellt – die Zertifikate müssen nicht neu ausgestellt werden (schont auch das Rate-Limit). Ein verschlüsseltes Off-Site- Backup dieser Dateien bauen wir im Restic-Tutorial.
• Zertifikate erneuern sich automatisch. Let’s-Encrypt-Zertifikate laufen nach 90 Tagen ab; Traefik verlängert sie rechtzeitig von selbst – kein Cronjob nötig. Kontrollieren kannst du das Ablaufdatum jederzeit, indem du an den openssl-Befehl aus Schritt 4 statt -issuer einfach -dates hängst (zeigt notBefore/notAfter).
• Traefik-Version pflegen. Der feste Tag (traefik:v3.7) bedeutet: Updates spielst du bewusst ein. Vor einem Sprung auf eine neue Minor-/Major-Version die Release-Notes lesen – Traefik hat zwischen v2 und v3 z. B. Label-Syntax geändert.
• Dashboard im Blick behalten. Ein kurzer Login zeigt, ob alle Router „grün" sind – die schnellste Kontrolle, ob nach einem Deploy alles hängt.

Ab jetzt ist der Weg für jede App gleich: Container ins proxy-Netzwerk, vier Labels dran, DNS-Record setzen – fertig ist ein öffentlich erreichbarer Dienst mit HTTPS. Als erste echte App hängen wir im nächsten Rezept Uptime Kuma hinter Traefik und überwachen damit alle folgenden Dienste.