Reverse Proxy mit Traefik, Raspberry Pi und Docker:

Reverse Proxy mit Traefik:
Docker-Container auf dem Raspberry Pi über .local-Domains erreichen

In diesem Tutorial zeige ich dir Schritt für Schritt, wie du Traefik als Reverse Proxy auf deinem Raspberry Pi einrichtest.
Mit dieser Konfiguration greifst du auf deine Docker-Container über benutzerfreundliche .local-Domains zu, statt komplizierte Portnummern zu verwenden. Die präzisen Anweisungen umfassen die vollständige Verzeichnisstruktur, alle notwendigen Docker Compose Dateien und die exakte Traefik-Konfiguration.
Ein besonderer Vorteil: Im Gegensatz zu anderen Reverse Proxy-Lösungen erkennt Traefik neue Docker-Container automatisch anhand der Labels, wodurch sich der Konfigurationsaufwand erheblich reduziert.
Die Anleitung enthält zudem spezifische Troubleshooting-Tipps für typische Fehlerquellen bei der Einrichtung des Reverse-Proxys in deinem Heimnetzwerk.

DarkWolfCave.de

Einleitung

In diesem Artikel dokumentiere ich die Installation und Konfiguration von Traefik als Reverse Proxy auf dem Raspberry Pi mit Docker. Die Anleitung zeigt die exakte Einrichtung eines Systems, mit dem du deine Docker-Container über intuitive URLs wie grafana.local oder bookstack.local erreichst – eine praktische Alternative zu numerischen Ports.

Traefik funktioniert als HTTP-Reverse-Proxy mit spezifischer Docker-Integration. Der technische Hauptvorteil: Traefik überwacht die Docker-Socket-API und erkennt automatisch neue Container. Für jeden Container mit entsprechenden Labels generiert Traefik die Routing-Konfiguration ohne manuelle Eingriffe. Diese Funktionsweise unterscheidet sich von klassischen Reverse Proxies wie Nginx oder HAProxy, bei denen jeder neue Dienst eine Anpassung der Konfigurationsdateien erfordert.

Voraussetzungen

Für diese Implementierung benötigst du:

• Raspberry Pi 3 oder neuer (mindestens 2 GB RAM)
• Raspberry Pi OS Lite (64-Bit empfohlen bei Pi 4/400 oder neuer)
• Docker Engine 20.10.x oder neuer
• Docker Compose v2
• Pi-hole für lokale DNS-Auflösung (optional, aber empfohlen)
• SSH-Zugang zum Raspberry Pi
• Statische IP-Adresse für den Raspberry Pi im lokalen Netzwerk

Falls Docker bisher nicht installiert ist, kannst du folgende Befehle verwenden oder in den entsprechenden Artikel von mir hineinschauen:

# Docker installieren
curl -sSL https://get.docker.com | sh

# Deinen Benutzer zur Docker-Gruppe hinzufügen
sudo usermod -aG docker $USER

# Docker Compose installieren
sudo apt-get update
sudo apt-get install -y docker-compose-plugin

# Einmal die Gruppenrichtlinien neu starten
newgrp docker

Traefik-Architektur im lokalen Netzwerk

Bei dieser Konfiguration fungiert dein Raspberry Pi (z.B. mit IP 192.168.1.36) als zentraler Einstiegspunkt (Entrypoint) für alle deine Docker-Dienste im Netzwerk:

1. Client-Anfragen, wie http://bookstack.local werden über DNS (Pi-hole) zur IP deines Raspberry Pi aufgelöst
2. Traefik empfängt alle Anfragen auf Port 80 (HTTP)
3. Basierend auf dem Host-Header (bookstack.local) leitet Traefik die Anfrage an den entsprechenden Container weiter
4. Die Antwort wird zurück an den Client gesendet

Verzeichnisstruktur vorbereiten

Wir beginnen mit der Erstellung einer sauberen Verzeichnisstruktur für unsere Reverse Proxy Traefik-Installation:

# Hauptverzeichnis sowie config-Verzeichnis für Docker-Projekte erstellen
# mit diesem Befehl werden alle Ordner und Unterordner erzeugt, falls sie nicht vorhanden sind. 

mkdir -p ~/docker/traefik/config

# In das Traefik-Verzeichnis wechseln
cd ~/docker/traefik

Traefik-Konfiguration erstellen

Die Konfiguration des Reverse Proxy besteht aus zwei Hauptdateien:
der Docker Compose Definition und der Traefik-Hauptkonfiguration.

Docker Compose Datei

Erstelle eine docker-compose.yml Datei im Traefik-Verzeichnis:

nano docker-compose.yml

Füge folgenden Inhalt ein, der den Reverse Proxy als Container einrichtet:

services:
  traefik:
    image: traefik:latest
    container_name: traefik
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    ports:
      - "80:80"      # HTTP
      - "8080:8080"  # Traefik Dashboard
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro # Docker-Socket für Container-Erkennung
      - ./config/traefik.yml:/etc/traefik/traefik.yml:ro # Hauptkonfiguration
    networks:
      - traefik_network
    labels:
      - "traefik.enable=true"
      # Dashboard lokal verfügbar machen
      - "traefik.http.routers.dashboard.rule=Host(`traefik.local`)"
      - "traefik.http.routers.dashboard.service=api@internal"
      - "traefik.http.routers.dashboard.entrypoints=web"

networks:
  traefik_network:
    name: traefik_network

Diese Konfiguration definiert:

• Den Traefik Reverse Proxy in seiner neuesten Version (:latest)
• Die notwendigen Ports für HTTP (80) und das Admin-Dashboard (8080)
• Die erforderlichen Volumes für Docker-Socket und Konfigurationsdatei
• Ein dediziertes Netzwerk für die Container-Kommunikation (traefik_network)
• Labels für den Dashboard-Zugriff über traefik.local

Traefik Hauptkonfiguration

Erstelle die Hauptkonfigurationsdatei für den Reverse Proxy:

cd config
nano traefik.yml

Füge folgenden Inhalt ein:

# Globale Konfiguration
global:
  checkNewVersion: true
  sendAnonymousUsage: false

# Log-Konfiguration
log:
  level: INFO
  # Für detailliertere Logs während der Einrichtung: level: DEBUG

# Traefik API und Dashboard aktivieren
api:
  dashboard: true
  insecure: true  # Im lokalen Netzwerk akzeptabel

# EntryPoints konfigurieren (Zugangspunkte für Anfragen)
entryPoints:
  web:
    address: ":80"

# Provider konfigurieren
providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false  # Container müssen explizit per Label aktiviert werden
    network: traefik_network

Diese YAML-Konfiguration definiert die zentralen Komponenten des Traefik Reverse Proxy:

• Globale Einstellungen und Logging-Parameter
• Das Dashboard für die Verwaltung und Überwachung
• Den „web“ Entrypoint auf Port 80 für HTTP-Anfragen
• Die Docker-Integration für die automatische Container-Erkennung

Traefik Reverse Proxy starten

Nach dieser Konfiguration können wir den Reverse-Proxy starten:

cd ~/docker/traefik
docker compose up -d

Der Parameter -d startet den Reverse Proxy im Hintergrund (detached mode). Prüfe anschließend den Status des Containers:

docker ps | grep traefik

Die Ausgabe sollte einen laufenden Traefik-Container anzeigen. Bei korrekter Konfiguration erscheint etwa Folgendes:

CONTAINER ID   IMAGE          COMMAND                  CREATED          STATUS          PORTS                                        NAMES
a1b2c3d4e5f6   traefik:v3.0   "/entrypoint.sh trae…"   2 minutes ago    Up 2 minutes    0.0.0.0:80->80/tcp, 0.0.0.0:8080->8080/tcp   traefik

Überprüfe die Logs des Reverse Proxy auf mögliche Fehler oder Warnungen:

docker logs traefik

In den Logs sollte die erfolgreiche Initialisierung des Traefik Reverse Proxy ohne Fehlermeldungen zu sehen sein. Wichtige Indikatoren sind:

• Die Bestätigung des Docker-Provider-Starts
• Die Aktivierung des Dashboards
• Die Konfiguration des „web“ Entrypoints auf Port 80

Zur Überprüfung des Dashboard-Zugangs öffne in deinem Browser:

http://[Raspberry-Pi-IP]:8080

Ersetze [Raspberry-Pi-IP] durch die tatsächliche IP-Adresse deines Raspberry Pi, beispielsweise http://192.168.1.36:8080. Das Dashboard bietet:

• Übersicht über konfigurierte Entrypoints
• Aktuell registrierte Routen des Reverse Proxy
• Status der Services und Router
• Visualisierung der HTTP-Middleware

Sollte das Dashboard nicht erreichbar sein, prüfe folgende Aspekte:

1. Läuft der Container? (docker ps)
2. Sind die Ports korrekt freigegeben? (netstat -tulpn | grep 8080)
3. Ist die Firewall konfiguriert? (sudo ufw status)

DNS-Konfiguration mit Pi-hole

Für die Namensauflösung der lokalen Domains benötigst du einen DNS-Server, der die lokalen Hostnamen auf die IP-Adresse deines Raspberry Pi auflöst. Oder du musst bei jedem Gerät die Hosts-Datei entsprechend anpassen. Dies ist aber bei mehreren Geräten sehr aufwendig und lästig.

Daher bietet sich Pi-hole hierfür ideal an, da es:

• Als lokaler DNS-Server fungiert
• Benutzerdefinierte DNS-Einträge erlaubt
• Zusätzlichen Werbeschutz bietet

Konfiguriere in Pi-hole die benötigten DNS-Einträge für den Reverse Proxy:

1. Öffne die Pi-hole Admin-Oberfläche in deinem Browser
2. Navigiere zu „Local DNS“ > „DNS Records“
3. Füge für jeden hinter dem Reverse Proxy betriebenen Service einen separaten Eintrag hinzu:

Domain	IP-Adresse
traefik.local	192.168.1.36
bookstack.local	192.168.1.36
grafana.local	192.168.1.36

Ersetze 192.168.1.36 mit der tatsächlichen IP-Adresse deines Raspberry Pi, auf dem der Reverse Proxy läuft.

Mit dieser Konfiguration wird jede Anfrage an beispielsweise bookstack.local an den Raspberry Pi weitergeleitet, wo der Traefik Reverse Proxy anhand des Host-Headers die Anfrage an den korrekten Container weiterleitet.

Um die Namensauflösung lokal ohne Pi-hole mithilfe der hosts-Datei auf deinen Geräten zu konfigurieren, kannst du die folgenden Schritte ausführen. Beachte, dass du dies auf jedem Gerät separat durchführen musst:

DNS-Konfiguration über die hosts-Datei

Du hast keinen Pi-hole am laufen?! Keine Sorge, du kannst die DNS-Einträge auch lokal auf jedem Gerät hinterlegen:

hosts-Datei auf dem Gerät finden:

• Linux/Mac: Öffne ein Terminal und bearbeite die Datei /etc/hosts. Du benötigst Root-/Administratorrechte, um diese Datei zu ändern.
  bash sudo nano /etc/hosts
• Windows: Öffne den Editor als Administrator und lade die Datei C:\Windows\System32\drivers\etc\hosts.

Einträge für lokale Domains hinzufügen:

• Füge am Ende der Datei die lokalen Domain-Einträge hinzu. Verwende dabei die IP-Adresse deines Raspberry Pi, auf dem der Reverse Proxy läuft.

   192.168.1.36    traefik.local
   192.168.1.36    bookstack.local
   192.168.1.36    grafana.local

Speichern und Schließen:

• Speichere die Datei und schließe den Editor. Bei Linux/Mac kannst du dies in nano mit CTRL+X, Y und Enter tun.

Gerät neu starten oder DNS-Cache leeren:

• Um die Änderungen wirksam zu machen, starte dein Gerät neu oder leere den DNS-Cache:
  • Linux: bash sudo systemctl restart nscd
  • Mac: bash sudo dscacheutil -flushcache
  • Windows: Öffne die Eingabeaufforderung als Administrator und führe aus:
    shell ipconfig /flushdns

Nach diesen Schritten sollten Anfragen an traefik.local, bookstack.local und grafana.local korrekt an deinen Raspberry Pi weitergeleitet werden, ohne Pi-hole zu verwenden. Allerdings musst du diesen Vorgang für jedes Gerät im Netzwerk wiederholen.

Pi-hole hinter dem Reverse Proxy einrichten

Wenn Pi-hole auf demselben Raspberry Pi wie der Traefik Reverse Proxy betrieben wird, entsteht ein Portkonflikt, da beide Dienste standardmäßig Port 80 benötigen. Diese Konfiguration löst den Konflikt durch Anpassung des Pi-hole-Webinterfaces. Dazu musst du lediglich die docker-compose.yml für deinen Pi-hole-Container anpassen:

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    restart: unless-stopped
    environment:
      TZ: 'Europe/Berlin'
      WEBPASSWORD: 'dein-passwort'  # Ersetze mit einem sicheren Passwort
      ServerIP: '192.168.1.36'      # IP-Adresse des Raspberry Pi
      WEB_PORT: '8080'              # Geändert von 80 auf 8080 für internen Webserver
    volumes:
      - './etc-pihole:/etc/pihole'
      - './etc-dnsmasq.d:/etc/dnsmasq.d'
    dns:
      - 127.0.0.1  # Pi-hole verwendet sich selbst als primären DNS
      - 1.1.1.1    # Cloudflare als Upstream-DNS
    networks:
      - traefik_network
    ports:
      - "53:53/tcp"  # DNS über TCP
      - "53:53/udp"  # DNS über UDP
    labels:
      - "traefik.enable=true"  # Aktiviert Integration mit dem Reverse Proxy
      - "traefik.http.routers.pihole.rule=Host(`pihole.local`)"  # Domain für Pi-hole
      - "traefik.http.services.pihole.loadbalancer.server.port=8080"  # Interner Port des Pi-hole Webinterfaces
networks:
  traefik_network:
    external: true  # Verwendet das bereits vom Reverse Proxy erstellte Netzwerk

Diese Konfiguration bewirkt:

1. Pi-hole verwendet intern Port 8080 für sein Webinterface (über WEB_PORT)
2. Die DNS-Dienste bleiben auf Port 53 (TCP/UDP) verfügbar
3. Der Traefik Reverse Proxy leitet Anfragen von pihole.local an den internen Port 8080 des Pi-hole-Containers weiter
4. Beide Dienste sind Teil des traefik_network, ermöglichen aber eine saubere Trennung der HTTP-Dienste

Jetzt musst du nur noch deinen Pi-Hole-Container stoppen und neu starten:

docker compose down
docker compose up -d

Beispiel: BookStack hinter dem Reverse Proxy Traefik einrichten

BookStack ist ein Wiki-System, das aus mehreren Containern besteht und daher ein gutes Beispiel für die Einrichtung einer komplexeren Anwendung hinter dem Reverse Proxy darstellt:

Zuerst erstellen wir wieder einen neuen Ordner für BookStack:

mkdir -p ~/docker/bookstack
cd ~/docker/bookstack

Dann benötigen wir die docker-compose.yml:

nano docker-compose.yml

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    restart: unless-stopped
    depends_on:
      - mariadb
    environment:
      - APP_URL=http://bookstack.local
      - APP_KEY=base64:Kf8Y2LkN3OPqwM9Zy1xzT4PgZ/cDlVoXRD196tcQD/A=
      - DB_HOST=mariadb
      - DB_PORT=3306
      - DB_DATABASE=bookstack
      - DB_USERNAME=bookstack
      - DB_PASSWORD=geheimespasswort
    volumes:
      - ./bookstack_data:/config
    networks:
      - traefik_network
    ports:
      - "6875:80"  # Optional: für direkten Zugriff ohne Traefik
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.bookstack.rule=Host(`bookstack.local`)"
      - "traefik.http.routers.bookstack.entrypoints=web"
      - "traefik.http.services.bookstack.loadbalancer.server.port=80"  # Interner Container-Port!

  mariadb:
    image: mariadb:10.5
    container_name: bookstack_db
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=supergeheim
      - MYSQL_DATABASE=bookstack
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=geheimespasswort
    volumes:
      - ./mariadb_data:/var/lib/mysql
    networks:
      - traefik_network

networks:
  traefik_network:
    external: true

Wichtige Konfigurationsdetails:

1. APP_URL: Muss exakt mit der URL übereinstimmen, unter der BookStack über den Reverse Proxy erreichbar sein soll
2. traefik.http.services.bookstack.loadbalancer.server.port: Definiert den internen Port des Containers (80), nicht den externen Port
3. networks: Alle Container müssen im traefik_network sein, um mit dem Reverse Proxy und untereinander kommunizieren zu können
4. depends_on: Stellt sicher, dass die Datenbank vor der Anwendung gestartet wird

Speichere diese Konfiguration und starte BookStack:

# Starte die Container
docker compose up -d

Nach dem erfolgreichen Start ist BookStack über http://bookstack.local erreichbar, wobei der Traefik Reverse Proxy die Anfragen entsprechend der Host-Header-Analyse an den korrekten Container weiterleitet. Natürlich musst du den DNS-Eintrag entweder in deiner Hosts-Datei oder in Pi-hole eingerichtet haben!

Template für weitere Container

Hier ist ein allgemeines Template, das du für weitere deine Docker-Container verwenden kannst, wenn du diese über den Traefik Reverse Proxy verwalten lassen möchtest.

services:
  myservice:
    image: image/name:tag
    container_name: myservice
    restart: unless-stopped
    volumes:
      - ./data:/pfad/im/container
    networks:
      - traefik_network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.myservice.rule=Host(`myservice.local`)"
      - "traefik.http.routers.myservice.entrypoints=web"
      - "traefik.http.services.myservice.loadbalancer.server.port=CONTAINER_PORT"

networks:
  traefik_network:
    external: true

Ersetze myservice, image/name:tag und CONTAINER_PORT entsprechend deinen Anforderungen.

Häufige Fehler und Troubleshooting

Container ist nicht über Traefik erreichbar

Prüfe folgende Punkte:

1. Labels korrekt? Besonders häufig werden falsche Ports angegeben. Beachte: In loadbalancer.server.port musst du den internen Container-Port angeben, nicht den externen Port.
2. Netzwerke verbunden? Der Container muss im Traefik-Netzwerk sein:

   networks:
     - traefik_network

3. DNS-Eintrag vorhanden? Überprüfe in Pi-hole, ob der Hostname richtig zur Raspberry Pi-IP aufgelöst wird.
4. Logs prüfen:

   docker logs traefik
   docker logs dein_container_name

Container startet nicht

Wenn ein Container nicht startet, prüfe die Logs:

docker logs dein_container_name

Häufige Ursachen:

• Fehlerhafte Umgebungsvariablen
• Bereits belegte Ports
• Fehlende Berechtigungen für Volume-Mounts

Erweiterte Konfigurationen

Mehrere Hosts für einen Container

Du kannst mehrere Hostnamen für einen Container definieren, musst diese dann aber auch im DNS angeben:

- "traefik.http.routers.myservice.rule=Host(`service.local`) || Host(`alternative.local`)"

Pfadbasiertes Routing

Statt über Hostnamen kannst du auch über Pfade routen:

- "traefik.http.routers.myservice.rule=PathPrefix(`/meinservice`)"

HTTP Basic Auth hinzufügen

Für einen – wirklich sehr- einfachen Passwortschutz:

# htpasswd installieren
sudo apt-get install -y apache2-utils

# Passwort-Hash erzeugen
htpasswd -nb benutzername passwort

Den generierten Hash dann in der Container-Konfiguration verwenden:

- "traefik.http.middlewares.auth.basicauth.users=benutzername:$$hashedpassword"
- "traefik.http.routers.myservice.middlewares=auth"

Geschafft!

Mit Traefik hast du einen leistungsstarken und zugleich einfach zu bedienenden Reverse Proxy für deine Docker-Container auf dem Raspberry Pi eingerichtet. Du kannst nun alle deine Services über benutzerfreundliche URLs wie bookstack.local oder grafana.local erreichen, ohne dir Portnummern merken zu müssen.

Das Schöne an Traefik ist seine nahtlose Integration mit Docker: Sobald du einen neuen Container mit den richtigen Labels startest, wird er automatisch in Traefik registriert und ist über die konfigurierte URL erreichbar.

Mit Pi-hole für die DNS-Auflösung und Traefik für das Routing hast du eine elegante, leichtgewichtige Lösung geschaffen, die selbst komplexe Setups übersichtlich hält und einfach zu erweitern ist.

Ich hoffe, dieser Artikel hilft dir bei deinen eigenen Projekten.
Fragen und Anregungen sind wie immer willkommen!