Was bauen wir?

Am Ende läuft Immich v3 hinter deinem Traefik-Proxy, erreichbar unter https://photos.DEINE_DOMAIN mit gültigem HTTPS. Die offizielle Immich-Handy-App sichert deine neuen Fotos und Videos dann automatisch auf deinen Server – wie die Cloud-Sicherung von Google Fotos, nur dass die Bilder ausschließlich bei dir liegen. Über die Web-Oberfläche durchstöberst du deine Zeitleiste, suchst per Volltext („Strand", „Hund") und lässt Immich Gesichter gruppieren.

Immich besteht aus vier Containern: dem Server (Web + API), einem Machine-Learning-Dienst (für Suche und Gesichtserkennung), einer PostgreSQL-Datenbank mit Vektor-Erweiterung und einem Cache (Valkey). Klingt nach viel – die offizielle Vorlage nimmt uns aber den Großteil ab, und wir hängen davon nur den Server an Traefik.

Der Reiz gegenüber Google Fotos: Die Bilder verlassen deinen Server nicht, es gibt keine Speicherplatz-Abos und keine automatische Auswertung deiner Aufnahmen durch einen Konzern. Dafür trägst du die Verantwortung für Betrieb und – ganz wichtig – für Backups: Wenn der Server stirbt und du keine Sicherung hast, sind die Fotos weg. Genau deshalb steht das Backup weiter unten nicht als Kür, sondern als Pflicht.

Voraussetzungen

• Ein laufender Traefik-Reverse-Proxy mit dem proxy-Netzwerk und dem Let’s-Encrypt-Resolver le – siehe Reverse Proxy mit Traefik.
• Eine Subdomain photos.DEINE_DOMAIN mit DNS-Record auf deine Server-IP – siehe Domain mit Server verbinden.
• Ein Backup. Deine Fotosammlung ist unersetzlich – richte zuerst Backups mit Restic ein.

Wie viel RAM deine Foto-Bibliothek samt KI-Suche wirklich braucht, rechnet dir der Server-Rechner aus.

Schritt für Schritt

Schritt 1: DNS-Record anlegen

Lege einen Eintrag photos.DEINE_DOMAIN an, der auf deine Server-IP zeigt, und prüfe ihn:

dig +short photos.DEINE_DOMAIN

Es muss deine Server-IP zurückkommen – sonst holt Traefik später kein Zertifikat.

Schritt 2: Ordner und .env vorbereiten

Immich wird über eine .env-Datei konfiguriert. Leg das Projekt an:

mkdir -p ~/immich && cd ~/immich

Erstelle eine .env mit den Kernwerten (ein starkes DB-Passwort einsetzen – nur Buchstaben und Ziffern, keine Sonderzeichen, das mag Immichs DB-Init nicht):

UPLOAD_LOCATION=./library
DB_DATA_LOCATION=./postgres
DB_PASSWORD=DEIN_DB_PASSWORT
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
IMMICH_VERSION=v3.0.3

• UPLOAD_LOCATION – hier landen deine Fotos und Videos. Das ist das wichtigste Verzeichnis fürs Backup.
• DB_DATA_LOCATION – die PostgreSQL-Daten. Muss auf einer lokalen Platte liegen (kein Netzlaufwerk/NFS – die DB nimmt das übel).
• IMMICH_VERSION – die gepinnte Version.

Schritt 3: Die compose.yaml anlegen

Wir übernehmen die offizielle Immich-Vorlage und ergänzen nur die Traefik-Labels am immich-server. Erstelle compose.yaml:

name: immich
services:
  immich-server:
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION}
    volumes:
      - ${UPLOAD_LOCATION}:/data
      - /etc/localtime:/etc/localtime:ro
    env_file: .env
    environment:
      DB_HOSTNAME: database
      REDIS_HOSTNAME: redis
    depends_on:
      redis:
        condition: service_started
      database:
        condition: service_healthy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.immich.rule=Host(`photos.DEINE_DOMAIN`)"
      - "traefik.http.routers.immich.entrypoints=websecure"
      - "traefik.http.routers.immich.tls.certresolver=le"
      - "traefik.http.services.immich.loadbalancer.server.port=2283"
    networks: [default, proxy]
    restart: unless-stopped

  immich-machine-learning:
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION}
    volumes:
      - model-cache:/cache
    networks: [default]
    restart: unless-stopped

  redis:
    image: docker.io/valkey/valkey:9
    networks: [default]
    restart: unless-stopped

  database:
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USERNAME} -d ${DB_DATABASE_NAME}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks: [default]
    restart: unless-stopped

volumes:
  model-cache:

networks:
  default:
  proxy:
    external: true

Wichtig zu verstehen:

• Nur immich-server hängt im proxy-Netz und trägt Traefik-Labels. Der ML-Dienst, Valkey und die Datenbank bleiben ausschließlich im internen default-Netz – von außen nicht erreichbar.
• loadbalancer.server.port=2283 – Immich lauscht im Container auf Port 2283.
• Die Datenbank ist bewusst das vorgebaute Immich-Postgres-Image mit der Vektor-Erweiterung VectorChord (für die Bildsuche). Nimm nicht einfach ein Standard-postgres – die Erweiterung fehlt dann.
• Valkey ist der Redis-Nachfolger; der Service heißt in der Immich-Vorlage aus Kompatibilitätsgründen weiterhin redis.
• Der Healthcheck an der Datenbank meldet, wann Postgres wirklich bereit ist. Über depends_on: … condition: service_healthy startet immich-server erst dann – das verhindert Migrationsfehler und den „Datenbank nicht erreichbar"-Start beim ersten Hochfahren.

Schritt 4: Große Uploads erlauben (Traefik-Timeout)

Das ist der Stolperstein bei Immich hinter Traefik: Standardmäßig bricht Traefik Verbindungen nach 60 Sekunden ab (readTimeout). Beim Hochladen großer Videos vom Handy führt das zu abgebrochenen Uploads (Fehler 502/499). Erhöhe den Timeout am websecure-Entrypoint in deiner Traefik-Konfiguration (der traefik-Service aus dem Traefik-Tutorial):

    command:
      # ... deine bestehenden Zeilen ...
      - "--entrypoints.websecure.transport.respondingTimeouts.readTimeout=600s"

Starte Traefik danach neu (docker compose up -d im Traefik-Ordner). Anders als nginx hat Traefik kein festes Größenlimit für Uploads – nur dieser Timeout muss hoch.

Schritt 5: Starten und den Erst-Setup durchlaufen

Zieh die Images (mehrere GB – das dauert) und starte:

docker compose up -d
docker compose logs -f immich-server

Die Images sind mehrere Gigabyte groß – der erste pull braucht je nach Anbindung ein paar Minuten. Prüfe danach, dass alle vier Container laufen:

docker compose ps

Du solltest immich-server, immich-machine-learning, redis und database mit Status running (die Datenbank healthy) sehen. Warte, bis im Log Immich Server is listening on http://[::1]:2283 [v3.0.3] erscheint. Ruf dann https://photos.DEINE_DOMAIN auf. Traefik holt beim ersten Zugriff das Let’s-Encrypt-Zertifikat (einen Moment Geduld). Beim allerersten Start begrüßt dich Immich mit „Willkommen bei Immich" und der Wahl, ob du neu startest oder eine Sicherung wiederherstellst:

![Der Willkommensbildschirm von Immich mit den Optionen „Erste Schritte" und „Von Datenbank wiederherstellen"](immich-willkommen.png “Erster Aufruf: „Erste Schritte” wählen für eine frische Installation")

Klick auf Erste Schritte (Wiederherstellen brauchst du nur, wenn du ein Backup einspielst). Danach legst du das Administrator-Konto an – als erster Nutzer wirst du automatisch Admin:

Nach dem ersten Login führt dich ein kurzer Einrichtungs-Assistent durch Theme, Sprache und Datenschutz-Grundeinstellungen:

Danach landest du auf deiner (noch leeren) Zeitleiste – das Herzstück von Immich:

Schritt 6: Die Handy-App verbinden

Der eigentliche Nutzen kommt von der App. Installiere Immich aus dem App Store bzw. Play Store (oder F-Droid). Beim Start fragt sie nach der Server-Adresse – trag https://photos.DEINE_DOMAIN ein und melde dich mit deinem Konto an. Aktiviere dann in den App-Einstellungen die Sicherung und wähle die Alben, die hochgeladen werden sollen.

Ab jetzt sichert dein Handy neue Fotos automatisch auf deinen Server – im Hintergrund und über WLAN. Der erste Durchlauf einer großen Mediathek dauert; danach kommen nur noch neue Aufnahmen dazu.

Nach dem Upload arbeitet Immich im Hintergrund weiter: Es erzeugt Vorschaubilder, liest die Aufnahme-Metadaten (Datum, Ort) aus und lässt den ML-Dienst Gesichter erkennen und die Bilder für die intelligente Suche indexieren. Diese Jobs laufen einige Zeit nach dem ersten großen Import – Gesichter und Suchtreffer tauchen also erst nach und nach auf. Den Fortschritt siehst du unter Administration → Auftragswarteschlangen. In der Seitenleiste findest du dann die typischen Foto-Funktionen: Erkunden (nach Personen und Orten), die Karte mit Geo-Verortung, Alben zum Teilen und die Rückblicke („Vor einem Jahr").

Wenn es nicht funktioniert

Symptom: Uploads großer Videos brechen nach etwa einer Minute ab (Fehler 502 oder 499).

Ursache & Lösung: Traefiks readTimeout (Standard 60 s) greift. Setz ihn wie in Schritt 4 auf 600s (oder höher) und starte Traefik neu. Das ist mit Abstand der häufigste Immich-hinter-Proxy-Fehler.

Symptom: Der immich-machine-learning-Container stürzt ab bzw. beendet sich mit „exit 137", Suche und Gesichtserkennung funktionieren nicht.

Ursache & Lösung: Zu wenig RAM – der Container wurde vom System beendet (Out of Memory). Gib dem Server mehr Speicher, oder deaktiviere ML, indem du den Service immich-machine-learning aus der compose.yaml entfernst. Immich läuft dann ohne Gesichtserkennung und intelligente Suche, aber Upload und Zeitleiste funktionieren normal.

Symptom: Nach einem Update starten die Container nicht mehr oder melden Migrationsfehler.

Ursache & Lösung: Server, Machine-Learning und Datenbank müssen auf derselben Version laufen. Setz in der .env die neue IMMICH_VERSION und aktualisiere alle Container gemeinsam (docker compose pull && docker compose up -d). Ein Downgrade nach einer Migration ist nicht möglich – nur ein Rücksetzen aus dem Backup.

Symptom: Immich zeigt „Wartungsmodus" / „Vorübergehend nicht verfügbar".

Ursache & Lösung: Immich v3 startet bei bestimmten Datenbank-Zuständen in einen Wartungsmodus. Im Log (docker compose logs immich-server) steht dann eine URL mit einem einmaligen Token (…/maintenance?token=…) – darüber meldest du dich am Wartungsmodus an und wählst „neu starten" bzw. beendest ihn. Danach ist die normale Oberfläche wieder da.

Symptom: Container startet nicht, „permission denied" beim Datenbank- oder Upload-Verzeichnis.

Ursache & Lösung: UPLOAD_LOCATION oder DB_DATA_LOCATION haben die falschen Zugriffsrechte oder liegen auf einem Netzlaufwerk. Lege beide auf einer lokalen Platte an und stelle sicher, dass Docker hineinschreiben darf.

Wartung & Backups

• Zwei Dinge gehören ins Backup – konsistent zusammen. Deine Fotos (UPLOAD_LOCATION, also ~/immich/library) und die Datenbank. Der DB-Dump enthält nur die Metadaten; ohne die passenden Dateien ist er wertlos, und umgekehrt. Am saubersten stoppst du Immich kurz und sicherst beides zusammen:

  Terminal

  docker compose stop immich-server
  docker compose exec -T database pg_dump --clean --if-exists \
    --dbname=immich --username=postgres | gzip > immich-db.sql.gz
  docker compose start immich-server

  Sichere den Dump zusammen mit dem library-Ordner verschlüsselt und off-site mit Restic. Alternativ kann Immich unter Administration → Auftragswarteschlangen automatische DB-Dumps erzeugen – die Fotos musst du trotzdem separat sichern.

• Den Ernstfall einmal proben. Ein Backup, das du nie zurückgespielt hast, ist nur eine Hoffnung. Zum Wiederherstellen spielst du den DB-Dump in eine frische Immich-Instanz gleicher Version ein und legst den library-Ordner an dieselbe Stelle – Immich bietet dafür beim ersten Start den Punkt „Von Datenbank wiederherstellen" an (der zweite Knopf aus Schritt 5). Wichtig ist die gleiche Version: Datenbank-Stand und Programm müssen zusammenpassen.

• Backup vor jedem Update. Weil Migrationen nicht umkehrbar sind, ist das Backup dein einziger Rückweg. Erst sichern, dann IMMICH_VERSION erhöhen, dann docker compose pull && docker compose up -d.

• Ehrlich zum Aufwand: Immich bringt oft mehrere Releases pro Monat. Du musst nicht jedem folgen – aber lies vor einem Sprung über mehrere Versionen die Release-Notes, und halte dich an die gepinnte Version, bis du bewusst aktualisierst.

• Speicherplatz im Blick behalten. Fotos und Videos wachsen stetig; Immich legt zusätzlich Vorschaubilder und umgewandelte Videos an. Überwache die Plattenbelegung (z. B. mit Uptime Kuma), damit dir der Server nicht volläuft.

Was bauen wir?

Am Ende läuft Paperless-ngx 2.20 hinter deinem Traefik-Proxy, erreichbar unter https://paperless.DEINE_DOMAIN mit HTTPS. Paperless ist ein Dokumenten-Management-System: Du fütterst es mit Scans oder PDFs, es liest den Text per OCR aus (auch aus reinen Bild-Scans), erkennt Datum und Inhalt und legt alles durchsuchbar ab. Über Tags, Korrespondenten und Dokumenttypen bringst du Ordnung hinein; die Volltextsuche findet später jedes Dokument.

Der Clou ist der Consume-Ordner: Alles, was du dort ablegst (z. B. vom Netzwerk-Scanner), wird automatisch importiert und verarbeitet. Paperless besteht aus fünf Containern – dem Webserver, einer PostgreSQL-Datenbank, einem Redis-Broker für die Hintergrundverarbeitung sowie Gotenberg und Tika, die Office-Dokumente in PDF umwandeln. Die offizielle Vorlage liefert das komplette Gespann.

Der Gewinn gegenüber einem Ordner voller PDFs auf der Festplatte: Paperless macht jedes Dokument durchsuchbar (auch eingescanntes Papier), hält Original und Archivversion sauber getrennt und lässt sich per Regeln automatisieren. Deine Unterlagen bleiben dabei auf deinem Server – kein Cloud-Dienst liest mit, und du bist nicht an ein proprietäres Format gebunden.

Voraussetzungen

• Ein laufender Traefik-Reverse-Proxy mit dem proxy-Netzwerk und dem Resolver le – siehe Reverse Proxy mit Traefik.
• Eine Subdomain paperless.DEINE_DOMAIN mit DNS-Record auf deine Server-IP – siehe Domain mit Server verbinden.
• Ein Backup. In Paperless landen deine wichtigsten Unterlagen – richte zuerst Backups mit Restic ein.

Unsicher, welche Server-Größe reicht? Der Server-Rechner rechnet dir RAM- und CPU-Bedarf für deine Dienste aus.

Schritt für Schritt

Schritt 1: DNS-Record anlegen

Lege paperless.DEINE_DOMAIN an (A/AAAA auf deine Server-IP) und prüfe:

dig +short paperless.DEINE_DOMAIN

Es muss deine Server-IP zurückkommen – sonst holt Traefik später kein Zertifikat.

Schritt 2: Einen Secret Key erzeugen

Paperless verschlüsselt Sitzungen mit einem geheimen Schlüssel. Der Default ist öffentlich bekannt – bei einer Instanz im Internet ein echtes Risiko. Erzeuge einen eigenen:

head -c 50 /dev/urandom | base64

Kopiere die Ausgabe – sie kommt gleich als PAPERLESS_SECRET_KEY in die Konfiguration.

Schritt 3: Die compose.yaml anlegen

Leg das Projekt an – inklusive der beiden Bind-Mount-Ordner:

mkdir -p ~/paperless/{consume,export} && cd ~/paperless

Die Unterordner consume und export legst du bewusst jetzt, als normaler Benutzer an: Würde erst der Docker-Daemon sie beim Start erzeugen, gehörten sie root – dann könnten weder du (cp in den Consume-Ordner) noch Paperless selbst (läuft via USERMAP_UID als UID 1000) hineinschreiben.

Erstelle compose.yaml. Ersetze paperless.DEINE_DOMAIN, die Passwörter und den PAPERLESS_SECRET_KEY:

name: paperless
services:
  broker:
    image: docker.io/library/redis:8
    volumes:
      - redisdata:/data
    networks: [default]
    restart: unless-stopped

  db:
    image: docker.io/library/postgres:18
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: EIN_STARKES_DB_PASSWORT
    volumes:
      - pgdata:/var/lib/postgresql
    networks: [default]
    restart: unless-stopped

  gotenberg:
    image: docker.io/gotenberg/gotenberg:8.34
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=file:///tmp/.*"
    networks: [default]
    restart: unless-stopped

  tika:
    image: docker.io/apache/tika:3.3.1.0
    networks: [default]
    restart: unless-stopped

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:2.20.15
    depends_on: [db, broker, gotenberg, tika]
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: EIN_STARKES_DB_PASSWORT
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998
      PAPERLESS_URL: https://paperless.DEINE_DOMAIN
      PAPERLESS_SECRET_KEY: DEIN_LANGER_SECRET_KEY
      PAPERLESS_OCR_LANGUAGE: deu
      PAPERLESS_TIME_ZONE: Europe/Berlin
      PAPERLESS_ADMIN_USER: admin
      PAPERLESS_ADMIN_PASSWORD: EIN_STARKES_ADMIN_PASSWORT
      USERMAP_UID: "1000"
      USERMAP_GID: "1000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.ppl.rule=Host(`paperless.DEINE_DOMAIN`)"
      - "traefik.http.routers.ppl.entrypoints=websecure"
      - "traefik.http.routers.ppl.tls.certresolver=le"
      - "traefik.http.services.ppl.loadbalancer.server.port=8000"
    networks: [default, proxy]
    restart: unless-stopped

volumes:
  data:
  media:
  pgdata:
  redisdata:

networks:
  default:
  proxy:
    external: true

Die wichtigsten Punkte:

• Nur webserver hängt im proxy-Netz und trägt Traefik-Labels (Port 8000). Die vier Hilfsdienste (db, broker, gotenberg, tika) bleiben intern.
• PAPERLESS_URL ist Pflicht hinter einem Proxy. Fehlt sie, weist Paperless den Login mit einem CSRF-/„403 Forbidden"-Fehler ab. Sie setzt zugleich die erlaubten Hosts und die vertrauenswürdigen Ursprünge.
• PAPERLESS_OCR_LANGUAGE: deu stellt die Texterkennung auf Deutsch. Deutsch, Englisch und ein paar weitere Sprachen sind im Image bereits enthalten – kein Zusatzpaket nötig.
• PAPERLESS_ADMIN_USER / _PASSWORD legen beim ersten Start automatisch den Superuser an, sodass du dich direkt anmelden kannst.
• USERMAP_UID/GID sollten zur Kennung deines Server-Benutzers passen (per id -u bzw. id -g ermitteln, meist 1000). Sonst gibt es „Permission denied" im Consume-Ordner.
• export und consume sind bewusst Ordner im Projektverzeichnis (Bind-Mounts): consume ist der Eingangskorb, export das Ziel für Backups.

Paperless nutzt insgesamt vier Speicherbereiche, die du auseinanderhalten solltest: media enthält deine verarbeiteten Dokumente (das Herzstück!), data den Suchindex und Hilfsdaten, consume ist der Eingangskorb und export das Backup-Ziel. Fürs Backup zählen media und data sowie die Datenbank – genau das nimmt dir der document_exporter weiter unten ab.

Schritt 4: Starten und anmelden

Zieh die Images (mehrere GB) und starte:

docker compose up -d
docker compose logs -f webserver

Beim ersten Start richtet Paperless die Datenbank ein (Migrationen) – das dauert einen Moment. Prüfe, dass alle fünf Container laufen:

docker compose ps

Du solltest webserver, db, broker, gotenberg und tika mit Status running sehen (der webserver wird nach kurzer Zeit healthy). Ist der Worker bereit (celery@… ready im Log), ruf https://paperless.DEINE_DOMAIN auf. Es erscheint die Anmeldeseite:

Melde dich mit admin und deinem Passwort an. Du landest auf der Startseite mit einer kurzen Willkommensmeldung und ersten Statistiken. Ganz unten links siehst du die laufende Version – praktisch, um vor einem Update den Ausgangsstand zu kennen. Die Sprache kannst du bei Bedarf unter Einstellungen umstellen; standardmäßig folgt Paperless der Sprache deines Browsers:

Schritt 5: Das erste Dokument einlesen

Jetzt der Kern. Es gibt drei Wege, ein Dokument hineinzubekommen:

1. Über die Weboberfläche: oben rechts auf Dokumente hochladen und eine PDF- oder Bilddatei auswählen.
2. Über den Consume-Ordner: Leg eine Datei in ~/paperless/consume – Paperless erkennt sie automatisch, verarbeitet sie und löscht sie danach aus dem Ordner. Ideal für einen Netzwerk-Scanner, der direkt dorthin scannt.
3. Aus einem Postfach: Paperless kann unter E-Mail ein IMAP-Konto abrufen und Anhänge automatisch einlesen – praktisch für Rechnungen, die dir ohnehin per Mail kommen.

cp ~/eine-rechnung.pdf ~/paperless/consume/

Paperless nimmt PDFs, Bilder (JPG/PNG/TIFF) und – dank Gotenberg und Tika – auch Office-Dateien wie Word oder Excel an. Bei einem reinen Bild-Scan liest die OCR den Text aus und legt ihn als durchsuchbare Ebene über das Dokument; bei einem PDF mit vorhandenem Textlayer überspringt Paperless die Erkennung und ist entsprechend schneller. Das Original bleibt dabei unangetastet erhalten – Paperless erzeugt zusätzlich eine durchsuchbare Archiv-Version.

Nach ein paar Sekunden (OCR braucht etwas Zeit) taucht das Dokument unter Dokumente auf – mit einer Vorschau und dem erkannten Titel:

Ein Klick öffnet die Detailansicht: links die Metadaten (Titel, Datum, Korrespondent, Tags) und die Reiter für Inhalt, Metadaten und Verlauf, rechts das Dokument mit einer zoombaren Vorschau. Paperless hat aus dem Scan bereits das Datum erkannt und schlägt es zur Bestätigung vor – genau das leistet die OCR im Hintergrund für dich:

Schritt 6: Ordnung mit Tags, Korrespondenten & Dokumenttypen

Damit die Suche später greift, vergibst du Tags (z. B. Steuer, Versicherung), ordnest einen Korrespondenten (den Absender) und einen Dokumenttyp (Rechnung, Vertrag …) zu. Das kannst du von Hand machen – oder Paperless über Arbeitsabläufe automatisieren: Regeln, die eingehende Dokumente anhand ihres Inhalts automatisch verschlagworten. So sortiert sich dein Archiv mit der Zeit von selbst.

Die Volltextsuche oben durchsucht danach nicht nur Titel und Tags, sondern den kompletten erkannten Text – eine Suche nach Rechnungsbetrag oder einem Kundennamen findet das passende Dokument in Sekunden. Kombiniert mit den Filtern (Korrespondent, Zeitraum, Dokumenttyp) wird der Papierstapel endgültig zum durchsuchbaren Archiv.

Ein einfaches Beispiel für einen Arbeitsablauf: Enthält ein neues Dokument das Wort „Stromabrechnung", vergib automatisch den Tag Energie, setz den Korrespondenten auf deinen Stromanbieter und den Dokumenttyp auf Rechnung. Solche Regeln legst du unter Verwaltung → Arbeitsabläufe an; sie greifen bei jedem eingehenden Dokument. Anfangs lohnt es sich, ein paar Dokumente von Hand zu sortieren – daraus siehst du schnell, welche Regeln sich wiederholen und automatisieren lassen. Nach ein paar Wochen landet der Großteil deiner Post ohne dein Zutun am richtigen Platz.

Wenn es nicht funktioniert

Symptom: Beim Login erscheint „Forbidden (403)" oder „CSRF verification failed".

Ursache & Lösung: PAPERLESS_URL ist nicht oder falsch gesetzt. Sie muss exakt deiner HTTPS-Adresse entsprechen (https://paperless.DEINE_DOMAIN, ohne Schrägstrich am Ende). Nach der Korrektur docker compose up -d.

Symptom: Dateien im Consume-Ordner werden nicht verarbeitet, „permission denied".

Ursache & Lösung: Häufigste Ursache: Die Ordner wurden nicht vorab angelegt (Schritt 3), sondern beim ersten Start vom Docker-Daemon erzeugt – dann gehören sie root. Mit sudo chown -R $(id -u):$(id -g) ~/paperless/consume ~/paperless/export gehören sie wieder dir. Ansonsten: USERMAP_UID/USERMAP_GID passen nicht zum Besitzer des Ordners – ermittle deine Kennung mit id -u und id -g, trag die Werte ein und starte neu.

Symptom: Hochgeladene Dokumente bleiben „in Bearbeitung" hängen.

Ursache & Lösung: Die Hintergrundverarbeitung läuft über Redis. Prüfe, dass der broker-Container läuft, und sieh unter Dateiaufgaben nach der Fehlermeldung der fehlgeschlagenen Aufgabe.

Symptom: Die Texterkennung liefert Unsinn oder erkennt nichts.

Ursache & Lösung: Falsche OCR-Sprache. Setz PAPERLESS_OCR_LANGUAGE=deu (oder deu+eng für gemischte Dokumente). Nur installierte Sprachen funktionieren.

Symptom: Office-Dokumente (Word, Excel) werden nicht angenommen oder enden im Timeout.

Ursache & Lösung: Dafür sind Gotenberg und Tika zuständig. Prüfe, dass beide Container laufen und PAPERLESS_TIKA_ENABLED=1 samt der beiden Endpoint-Variablen gesetzt ist.

Symptom: Beim Massenimport wird der Server sehr langsam, die CPU ist dauerhaft am Anschlag.

Ursache & Lösung: OCR ist rechenintensiv, und Paperless nutzt standardmäßig alle Kerne. Auf kleinen Servern kannst du die Last drosseln, indem du die Zahl der Worker bzw. Threads begrenzt (PAPERLESS_TASK_WORKERS, PAPERLESS_THREADS_PER_WORKER). Dann dauert der Import länger, aber die Oberfläche bleibt bedienbar.

Wartung & Backups

• Das saubere Backup macht der document_exporter. Er schreibt alle Dokumente, Vorschaubilder, Metadaten und den Datenbankinhalt in den export-Ordner – portabel und wieder importierbar:

  Terminal

  docker compose exec -T webserver document_exporter ../export

  Sichere den export-Ordner anschließend verschlüsselt und off-site mit Restic. Alternativ sicherst du die Volumes media, data und die Datenbank direkt – der Exporter ist aber der empfohlene, umzugssichere Weg.

• Beim Wiederherstellen die gleiche Version verwenden. Ein Export enthält ein Abbild passend zum Datenbank-Schema; spiel ihn nur in eine Paperless-Instanz derselben Version ein (document_importer ../export).

• Updates. Vor dem Update ein Backup ziehen, dann den Image-Tag erhöhen (z. B. 2.20.15 → nächste Version), docker compose pull und docker compose up -d. Die Datenbank-Migrationen laufen beim Start automatisch. Bleib bei der stabilen 2.x-Reihe – die 3.0-Beta ist noch nicht für den Produktivbetrieb gedacht.

• Backup automatisieren. Den document_exporter legst du am besten in einen täglichen Cron-Job (z. B. nachts), der anschließend den export-Ordner per Restic sichert. So hast du jeden Morgen einen frischen, wiederherstellbaren Stand – ohne daran denken zu müssen.

• Ehrlich zum Aufwand: Paperless läuft danach sehr wartungsarm. Der eigentliche Aufwand ist das Einsortieren neuer Dokumente – das nimmt dir mit etwas eingerichteter Automatik aber zunehmend die Software ab. Plane einmal die grobe Tag-Struktur, dann trägt sich das Archiv weitgehend selbst.

Was bauen wir?

Am Ende zeigt die Sicherheits- & Einrichtungsübersicht deiner Nextcloud keine Warnungen mehr. Konkret bauen wir auf der Installation aus Teil 1 auf und ergänzen: den fehlenden HSTS-Sicherheitsheader über Traefik, ein konfiguriertes Wartungsfenster, den funktionierenden E-Mail-Versand (für Passwort-Resets und Benachrichtigungen), eine erzwungene Zwei-Faktor-Authentifizierung und einen Brute-Force-Schutz, der die echten Angreifer-IPs sieht – die Grundlage für Fail2ban.

Getestet ist alles gegen Nextcloud 34.0.1 hinter Traefik v3.7 auf Debian 13 mit PHP 8.5. Das ist Fleißarbeit, aber genau die Fleißarbeit, die in 90 % aller Nextcloud-Anleitungen fehlt – und die den Unterschied zwischen „irgendwie online" und „vernünftig betrieben" ausmacht.

Voraussetzungen

• Eine laufende Nextcloud wie in Nextcloud selbst hosten (Teil 1) aufgesetzt: klassisches nextcloud-Image hinter Traefik, mit MariaDB, Redis und Cron-Sidecar. Die Container-Namen aus Teil 1 (nc-app, nc-db, nc-redis, nc-cron) und der Compose-Ordner ~/nextcloud sind hier die Basis.
• SSH-Zugriff auf den Server und das Kommandozeilen-Werkzeug occ – wir rufen es wie in Teil 1 im App-Container auf: docker exec -u www-data nc-app php occ <befehl>.
• Ein Traefik-Reverse-Proxy mit dem proxy-Netz und dem Resolver le wie im Tutorial Reverse Proxy mit Traefik – die Sicherheits-Header hängen wir als Traefik-Middleware an.

docker exec -u www-data nc-app php occ status

Schritt für Schritt

Schritt 1: Die Admin-Übersicht als Bestandsaufnahme lesen

Melde dich als Administrator an und öffne Administrationseinstellungen → Übersicht. Oben steht der Abschnitt „Sicherheits- & Einrichtungswarnungen". Direkt nach einer Standardinstallation sieht das so aus:

Nextcloud unterscheidet drei Stufen: gelbe Warnungen (⚠, solltest du beheben), blaue Hinweise (ℹ, meist optional) und stillschweigend bestandene Prüfungen. Bei unserer frischen Instanz stehen drei Warnungen und ein paar Hinweise an:

• ⚠ Beginn des Wartungsfensters ist nicht gesetzt (Schritt 2)
• ⚠ MIME-Type-Migrationen verfügbar (Schritt 2)
• ⚠ HTTP-Header – der Strict-Transport-Security-Header fehlt (Schritt 3)
• ℹ E-Mail-Test – noch kein Mailserver hinterlegt (Schritt 4)
• ℹ Zwei-Faktor-Konfiguration – 2FA ist verfügbar, aber nicht verpflichtend (Schritt 5)

Denselben Bericht bekommst du auch auf der Kommandozeile – praktisch, um den Fortschritt zwischendurch zu prüfen, ohne durch die Weboberfläche zu klicken:

docker exec -u www-data nc-app php occ setupchecks

Der Befehl gibt jede Prüfung mit ✓, ⚠ oder ✗ aus. Genau diese Liste arbeiten wir jetzt von oben nach unten ab.

Schritt 2: Die zwei schnellen Warnungen beheben

Zwei Warnungen sind mit je einem Befehl erledigt.

Wartungsfenster festlegen. Nextcloud führt einmal täglich rechenintensive Aufräumjobs aus (Vorschauen, Aktivitäten, Kalender-Wiederholungen). Ohne definiertes Zeitfenster laufen die irgendwann – auch mitten am Tag. Leg einen Startzeitpunkt fest, zu dem kaum jemand arbeitet. Der Wert ist eine volle Stunde in UTC; 1 legt den Beginn auf 01:00 UTC – der Check meldet danach das Fenster von 1:00 bis 7:00 UTC:

docker exec -u www-data nc-app php occ config:system:set maintenance_window_start --type=integer --value=1

Zur Kontrolle bestätigt der Setup-Check danach:

✓ Maintenance window start: Maintenance window to execute heavy background jobs is between 1:00 UTC and 7:00 UTC

MIME-Type-Migrationen ausführen. Gelegentlich lernt Nextcloud neue Dateitypen (etwa für bessere Icons und Vorschauen). Diese Migration läuft bei Updates nicht automatisch, weil sie auf großen Instanzen dauern kann. Auf einer frischen Cloud ist sie in Sekunden durch:

docker exec -u www-data nc-app php occ maintenance:repair --include-expensive

Du siehst eine Liste abgearbeiteter Reparaturschritte (u. a. Repair mime types). Danach meldet der Check Mimetype migrations available: None. Zwei Warnungen weniger.

Schritt 3: Den HSTS-Sicherheitsheader über Traefik setzen

Die dritte Warnung ist die wichtigste: Der Strict-Transport-Security-Header (HSTS) fehlt. Er weist den Browser an, diese Domain ausschließlich über HTTPS anzusprechen – auch dann, wenn jemand http:// eintippt oder ein Angreifer die Verbindung umzubiegen versucht. Ohne HSTS bleibt ein kleines Zeitfenster für Downgrade-Angriffe offen.

Weil unsere Nextcloud hinter Traefik sitzt, setzen wir den Header im Proxy, nicht in Nextcloud – dort gehört er hin, denn Traefik terminiert das TLS. Ergänze in der compose.yaml deiner Nextcloud (aus Teil 1) die Middleware nc-secure und häng sie an den Router. Konkret ändern sich zwei Stellen im labels-Block von nc-app.

Erstens die Router-Zeile um nc-secure erweitern:

      - "traefik.http.routers.nc.middlewares=nc-dav,nc-secure"

Zweitens die Header-Middleware definieren (direkt bei den anderen nc-app-Labels):

      - "traefik.http.middlewares.nc-secure.headers.stsSeconds=15552000"
      - "traefik.http.middlewares.nc-secure.headers.stsIncludeSubdomains=true"

stsSeconds=15552000 sind 180 Tage – der von Nextcloud geforderte Mindestwert. Übernimm die Änderung und lade nur den App-Container neu:

docker compose up -d nc-app

Prüfe nach ein paar Sekunden von deinem eigenen Rechner aus, dass der Header wirklich ausgeliefert wird:

curl -sS -I https://cloud.DEINE_DOMAIN/ | grep -i strict-transport

Du solltest genau das sehen:

strict-transport-security: max-age=15552000; includeSubDomains

In der Admin-Übersicht wird die HTTP-Header-Warnung damit grün: „Your server is correctly configured to send security headers." Die übrigen Header (X-Content-Type-Options, X-Frame-Options, Referrer-Policy …) liefert Nextcloud selbst aus – nur HSTS musste vom Proxy kommen.

Schritt 4: E-Mail-Versand einrichten

Ohne funktionierenden Mailversand kann Nextcloud keine Passwort-Resets verschicken, keine Freigabe-Benachrichtigungen und keine Sicherheitswarnungen – und der Hinweis „E-Mail-Test" bleibt stehen. Das holen wir nach.

Öffne Administrationseinstellungen → Grundeinstellungen und scroll zum Abschnitt „E-Mail-Server". Trag die Zugangsdaten deines Mail-Anbieters ein:

• Sendemodus: SMTP
• Verschlüsselung: SSL/TLS (Port 465) oder STARTTLS (Port 587) – nie unverschlüsselt
• Absenderadresse: z. B. cloud @ DEINE_DOMAIN
• Serveradresse: Host und Port deines Anbieters
• Authentifizierung: einschalten und Benutzername/Passwort hinterlegen

Trag oben unter Persönliche Informationen eine E-Mail-Adresse für dein Admin-Konto ein (dorthin geht die Testmail). Dann klick auf „Test-E-Mail senden". Kommt die Mail an, bestätigt Nextcloud das mit einer grünen Meldung:

Schritt 5: Zwei-Faktor-Authentifizierung erzwingen

Ein gestohlenes Passwort ist der häufigste Weg, wie Konten übernommen werden. Ein zweiter Faktor (ein zeitbasierter Code aus einer Authenticator-App, TOTP) macht das Passwort allein wertlos. Nextcloud bringt den passenden Anbieter schon mit – wir müssen ihn nur aktivieren und zur Pflicht machen.

Aktiviere zunächst die TOTP-App (sie ist im Lieferumfang enthalten):

docker exec -u www-data nc-app php occ app:enable twofactor_totp

Jeder Nutzer richtet seinen zweiten Faktor danach selbst ein – unter Persönliche Einstellungen → Sicherheit → „TOTP (Authenticator-App)". Beim Aktivieren zeigt Nextcloud einen QR-Code, den man mit einer App wie Aegis, andOTP oder Google Authenticator scannt. Zusätzlich empfiehlt sich die App „Zwei-Faktor-Backup-Codes" – die einmaligen Codes retten dich, wenn das Handy verloren geht.

Damit niemand die Absicherung „vergisst", erzwingst du 2FA für die Administratoren. Im Web findest du das unter Administrationseinstellungen → Sicherheit → „Zwei-Faktor- Authentifizierung erzwingen", per Kommandozeile geht es so:

docker exec -u www-data nc-app php occ twofactorauth:enforce --on --group=admin

Schritt 6: Brute-Force-Schutz mit echten IPs – Basis für Fail2ban

Nextcloud drosselt fehlgeschlagene Logins von Haus aus: Nach mehreren Fehlversuchen verzögert es weitere Anfragen derselben IP. Dieser Schutz steht und fällt aber damit, dass Nextcloud die echte Client-IP sieht – und nicht die interne IP von Traefik. Genau das leistet die TRUSTED_PROXIES-Einstellung aus Teil 1.

Ob es funktioniert, siehst du unter Administrationseinstellungen → Sicherheit im Kasten „Brute-Force-Zulassungsliste" (im Screenshot oben). Dort steht deine aktuelle, korrekt erkannte öffentliche IP:

Ihre aktuelle IP-Adresse wird als "DEINE_IP" erkannt. Diese Adresse wird derzeit nicht gedrosselt.

Steht da stattdessen eine 172.x.x.x-Adresse aus dem Docker-Netz, greift TRUSTED_PROXIES nicht – dann würde der Brute-Force-Schutz alle Nutzer über einen Kamm scheren und im Zweifel Traefik selbst sperren. In dem Fall zurück zu Teil 1, Schritt 2/3.

Harte Sperren mit Fail2ban. Die eingebaute Drosselung verzögert nur; wer Angreifer richtig aussperren will, kombiniert Nextcloud mit Fail2ban. Nextcloud protokolliert jeden Fehlversuch im JSON-Log – und dank TRUSTED_PROXIES mit der echten IP:

{"level":2,"time":"2026-07-18T08:14:05+00:00","remoteAddr":"203.0.113.47","user":"--","app":"no app in context","method":"POST","url":"/login","message":"Login failed: BENUTZER (Remote IP: 203.0.113.47)"}

Dieses Log liegt im Nextcloud-Volume. Den Pfad auf dem Host findest du so:

docker inspect -f '{{ range .Mounts }}{{ if eq .Destination "/var/www/html" }}{{ .Source }}{{ end }}{{ end }}' nc-app

Darunter liegt die Datei data/nextcloud.log. Auf die zeigst du einen Fail2ban-Filter, der auf remoteAddr matcht, plus ein Jail nach dem Muster aus dem Fail2ban-Tutorial. So wandert nach ein paar Fehlversuchen die Angreifer-IP direkt in die Firewall – bevor die Anfrage Nextcloud überhaupt erreicht.

Schritt 7: Caching & PHP prüfen – das Performance-Fundament

Zum Schluss vergewissern wir uns, dass die Performance-Basis steht. Vieles davon hat Teil 1 über die REDIS_HOST-Variable schon automatisch eingerichtet – prüfen schadet trotzdem nicht, denn genau hier wird eine Nextcloud zäh oder flott.

Nextcloud nutzt drei Cache-Rollen. Kontrolliere alle drei:

docker exec -u www-data nc-app php occ config:system:get memcache.local
docker exec -u www-data nc-app php occ config:system:get memcache.distributed
docker exec -u www-data nc-app php occ config:system:get memcache.locking

Erwartet:

\OC\Memcache\APCu
\OC\Memcache\Redis
\OC\Memcache\Redis

• Lokaler Cache (APCu): hält häufig genutzte Daten im RAM des PHP-Prozesses – der spürbarste Beschleuniger im Alltag.
• Verteilter Cache (Redis): teilt Cache-Daten über Prozesse hinweg, wichtig sobald App- und Cron-Container zusammenspielen.
• File-Locking (Redis): verhindert, dass zwei Zugriffe dieselbe Datei gleichzeitig verändern und sie beschädigen. Der Grund, warum wir in Teil 1 überhaupt Redis eingebaut haben.

Passt das Zusammenspiel, meldet docker exec -u www-data nc-app php occ setupchecks die Zeile ✓ Memcache: Configured. (Bestandene Prüfungen zeigt die Web-Übersicht nicht an – dort tauchen nur Warnungen und Hinweise auf, deshalb kontrollierst du das hier per CLI.)

OPcache – der Bytecode-Cache von PHP – ist im offiziellen nextcloud-Image bereits sinnvoll vorkonfiguriert (u. a. opcache.interned_strings_buffer=32). Du musst hier also nichts nachziehen; die früher berüchtigte OPcache-Warnung taucht mit aktuellen Images gar nicht mehr auf. Nachschauen kannst du bei Bedarf so:

docker exec -u www-data nc-app php -i | grep opcache.interned_strings_buffer

Damit ist die Übersicht warnungsfrei:

Wenn es nicht funktioniert

Symptom: Nach dem Traefik-Neustart erscheint der HSTS-Header nicht in der curl-Ausgabe.

Ursache & Lösung: Meist ist die Middleware nicht am Router. Prüfe, dass die Zeile traefik.http.routers.nc.middlewares beide Middlewares nennt (nc-dav,nc-secure) und dass die drei nc-secure-Header-Labels im nc-app-Block stehen. Danach docker compose up -d nc-app. Traefik übernimmt geänderte Labels erst beim Neu-Erstellen des Containers.

Symptom: Der E-Mail-Test schlägt fehl („Es gab ein Problem beim Senden der E-Mail").

Ursache & Lösung: Fast immer Port/Verschlüsselung oder Authentifizierung. Kombiniere SSL/TLS mit Port 465 oder STARTTLS mit Port 587 – nicht kreuzweise. Nutzt dein Anbieter 2FA, brauchst du ein App-Passwort (siehe Schritt 4). Details stehen im Nextcloud-Log: docker exec -u www-data nc-app php occ log:tail 20.

Symptom: Du kommst nach dem Erzwingen von 2FA selbst nicht mehr rein.

Ursache & Lösung: Du hattest noch keinen zweiten Faktor eingerichtet. Hebe die Pflicht per Kommandozeile auf, richte deinen Faktor in Ruhe ein und schalte sie danach wieder scharf: docker exec -u www-data nc-app php occ twofactorauth:enforce --off.

Symptom: Im Brute-Force-Kasten steht eine 172.x.x.x-Adresse statt deiner echten IP.

Ursache & Lösung: TRUSTED_PROXIES passt nicht zum tatsächlichen proxy-Subnetz. Ermittle es mit docker network inspect proxy -f '{{(index .IPAM.Config 0).Subnet}}' und trag den Wert in der nc-app-Umgebung ein (Teil 1, Schritt 2). Sonst sperrt der Brute-Force-Schutz im Ernstfall den Proxy und damit alle Nutzer.

Symptom: Nach einem Reboot meldet Nextcloud „Redis went away" oder wird sehr langsam.

Ursache & Lösung: Der App-Container ist vor Redis gestartet. Stelle sicher, dass nc-redis in depends_on steht (Teil 1) und mit restart: unless-stopped läuft – dann fängt Docker den Startreihenfolge-Fall selbst ab.

Wartung & Backups

• Übersicht nach jedem Update prüfen. Neue Nextcloud-Versionen bringen neue Checks mit. Wirf nach jedem Upgrade einen Blick auf Administrationseinstellungen → Übersicht oder lass occ setupchecks laufen – so fängst du neue Warnungen früh ab.
• Regelmäßig den offiziellen Security-Scan nutzen. Der Nextcloud Security Scan prüft deine Domain von außen und vergibt eine Note. Mit HSTS und aktuellen Versionen ist A/A+ das realistische Ziel; fällt die Note, ist meist ein Update überfällig.
• Zweite Faktoren im Blick behalten. Bewahre die Backup-Codes getrennt vom Handy auf. Verliert ein Nutzer sein Gerät, entfernst du seinen Faktor mit occ twofactorauth:disable BENUTZER totp, danach richtet er ihn neu ein.
• App-Passwörter aufräumen. Jeder verbundene Client (Desktop, Handy) bekommt ein eigenes App-Passwort. Unter Persönliche Einstellungen → Sicherheit siehst du alle Geräte und kannst einzelne bei Verlust gezielt widerrufen.
• Die Absicherung ersetzt kein Backup. All das schützt vor fremdem Zugriff, nicht vor Datenverlust. Die konsistente Sicherung aus Datenbank-Dump und Datenverzeichnis bleibt Pflicht – siehe den Wartungsabschnitt in Teil 1 und Backups mit Restic. Ehrlich zum Aufwand: Plane den monatlichen Update-Durchgang mit einem kurzen Blick auf die Übersicht fest ein – dann bleibt deine Cloud dauerhaft grün.

Was bauen wir?

Am Ende läuft Nextcloud 34 hinter deinem Traefik-Proxy, erreichbar unter https://cloud.DEINE_DOMAIN mit gültigem Let’s-Encrypt-Zertifikat. Nextcloud ist deine private Cloud: Dateien synchronisieren (wie bei Dropbox), Kalender und Kontakte über alle Geräte, Fotos, Notizen, Office-Dokumente. Du verbindest den offiziellen Desktop-Sync-Client und die Handy-Apps mit deinem Server – die Daten liegen dabei ausschließlich bei dir.

Wir setzen bewusst auf das klassische nextcloud-Image (nicht auf „Nextcloud All-in-One") plus MariaDB als Datenbank und Redis fürs Caching und File-Locking. Diese Kombination ist stabil, gut dokumentiert und passt exakt in das Traefik-Muster aus der Serverküche.

Voraussetzungen

• Ein laufender Traefik-Reverse-Proxy mit dem gemeinsamen proxy-Netzwerk und dem Let’s-Encrypt-Resolver le – wie im Tutorial Reverse Proxy mit Traefik aufgebaut.
• Eine Subdomain cloud.DEINE_DOMAIN, deren DNS-Record (A/AAAA) auf deine Server-IP zeigt – siehe Domain mit Server verbinden.
• Ein funktionierendes Backup. Eine Cloud ist der Ort, an dem Datenverlust am meisten wehtut – richte zuerst Backups mit Restic ein.

Wie groß dein Server für deine Nutzerzahl sein sollte, schätzt dir der Server-Rechner in ein paar Klicks.

Schritt für Schritt

Schritt 1: DNS-Record anlegen

Lege bei deinem DNS-Anbieter einen Eintrag cloud.DEINE_DOMAIN an, der auf deine Server-IP zeigt (A-Record für IPv4, AAAA für IPv6). Prüfe, dass er aufgelöst wird:

dig +short cloud.DEINE_DOMAIN

Du solltest deine Server-IP sehen. Erst wenn der Record steht, kann Traefik später das HTTPS-Zertifikat holen.

Schritt 2: Das proxy-Subnetz ermitteln

Nextcloud sitzt hinter Traefik. Damit Nextclouds Brute-Force-Schutz die echte Besucher-IP erkennt (und nicht die interne Traefik-IP sperrt), müssen wir Traefik als „vertrauenswürdigen Proxy" eintragen. Dazu brauchst du das Subnetz deines proxy-Netzwerks:

docker network inspect proxy -f '{{(index .IPAM.Config 0).Subnet}}'

Du bekommst etwas wie 172.18.0.0/16. Merke dir diesen Wert – er kommt gleich als TRUSTED_PROXIES in die Konfiguration.

Schritt 3: Die compose.yaml anlegen

Leg einen Ordner an und wechsle hinein:

mkdir -p ~/nextcloud && cd ~/nextcloud

Erstelle die compose.yaml. Ersetze cloud.DEINE_DOMAIN, alle Passwörter und das TRUSTED_PROXIES-Subnetz aus Schritt 2:

services:
  nc-db:
    image: mariadb:11.4
    container_name: nc-db
    command: --transaction-isolation=READ-COMMITTED --log-bin=binlog --binlog-format=ROW
    environment:
      MARIADB_ROOT_PASSWORD: EIN_STARKES_ROOT_PASSWORT
      MARIADB_DATABASE: nextcloud
      MARIADB_USER: nextcloud
      MARIADB_PASSWORD: EIN_STARKES_DB_PASSWORT
    volumes:
      - nc_db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 6
    networks: [default]
    restart: unless-stopped

  nc-redis:
    image: redis:8-alpine
    container_name: nc-redis
    command: redis-server --requirepass EIN_STARKES_REDIS_PASSWORT
    networks: [default]
    restart: unless-stopped

  nc-app:
    image: nextcloud:34-apache
    container_name: nc-app
    depends_on:
      nc-db:
        condition: service_healthy
      nc-redis:
        condition: service_started
    environment:
      MYSQL_HOST: nc-db
      MYSQL_DATABASE: nextcloud
      MYSQL_USER: nextcloud
      MYSQL_PASSWORD: EIN_STARKES_DB_PASSWORT
      REDIS_HOST: nc-redis
      REDIS_HOST_PASSWORD: EIN_STARKES_REDIS_PASSWORT
      NEXTCLOUD_TRUSTED_DOMAINS: cloud.DEINE_DOMAIN
      OVERWRITEPROTOCOL: https
      OVERWRITECLIURL: https://cloud.DEINE_DOMAIN
      TRUSTED_PROXIES: 172.18.0.0/16
      PHP_MEMORY_LIMIT: 1024M
      PHP_UPLOAD_LIMIT: 10G
    volumes:
      - nc_html:/var/www/html
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.nc.rule=Host(`cloud.DEINE_DOMAIN`)"
      - "traefik.http.routers.nc.entrypoints=websecure"
      - "traefik.http.routers.nc.tls.certresolver=le"
      - "traefik.http.routers.nc.middlewares=nc-dav"
      - "traefik.http.services.nc.loadbalancer.server.port=80"
      # .well-known-Redirect für CalDAV/CardDAV (siehe unten)
      - "traefik.http.middlewares.nc-dav.redirectregex.regex=https://(.*)/.well-known/(?:card|cal)dav"
      - "traefik.http.middlewares.nc-dav.redirectregex.replacement=https://cloud.DEINE_DOMAIN/remote.php/dav/"
      - "traefik.http.middlewares.nc-dav.redirectregex.permanent=true"
    networks: [default, proxy]
    restart: unless-stopped

volumes:
  nc_html:
  nc_db:

networks:
  default:
  proxy:
    external: true

Was hier wichtig ist:

• Drei Container: nc-app (Nextcloud), nc-db (MariaDB), nc-redis. Nur nc-app hängt im proxy-Netz (für Traefik) und im internen default-Netz. Datenbank und Redis bleiben ausschließlich intern – sie haben kein ports: und sind von außen nicht erreichbar.
• Zwei Named Volumes: nc_html (Programmcode, config.php, Nutzerdaten) und nc_db (die MariaDB-Daten). Das nc_db-Volume ist Pflicht: Ohne den Eintrag landet die Datenbank in einem anonymen Volume, und ein docker compose down gefolgt von up würde sie unwiederbringlich verlieren.
• healthcheck + depends_on: service_healthy: Nextcloud startet schneller als die Datenbank initialisiert ist. Ohne diesen Healthcheck scheitert die Erstinstallation an einem „Connection refused". So wartet der App-Container, bis MariaDB wirklich bereit ist.
• NEXTCLOUD_TRUSTED_DOMAINS: ohne die eigene Domain hier begrüßt dich Nextcloud mit „Zugriff über eine nicht vertrauenswürdige Domäne".
• OVERWRITEPROTOCOL: https sagt Nextcloud, dass es hinter HTTPS läuft – sonst baut es interne Links als http:// und Logins/Redirects brechen.
• TRUSTED_PROXIES: das Subnetz aus Schritt 2. Damit erkennt Nextcloud die echte Client-IP; sonst sperrt der Brute-Force-Schutz die Traefik-IP.
• PHP_MEMORY_LIMIT / PHP_UPLOAD_LIMIT: die Defaults (512 MB) sind für große Uploads zu klein. Hier großzügig gesetzt.
• loadbalancer.server.port=80: das Apache-Image lauscht im Container auf Port 80.
• Die nc-dav-Middleware löst ein klassisches Nextcloud-Problem – dazu gleich mehr.

Schritt 4: Starten und den Erst-Setup durchlaufen

Starte den Stack:

docker compose up -d

Beim ersten Start initialisiert MariaDB die Datenbank und Nextcloud entpackt sich – das dauert ein bis zwei Minuten. Verfolge es im Log:

docker compose logs -f nc-app

Beim ersten Lauf entpackt das Image Nextcloud ins Volume; du siehst Zeilen wie Initializing nextcloud 34.0.1.2 ... und schließlich Initializing finished, gefolgt vom Apache-Start. Erscheint stattdessen wiederholt restarting, wirf einen Blick in den Abschnitt „Wenn es nicht funktioniert". Mit Strg+C verlässt du die Log-Ansicht wieder (der Container läuft weiter).

Ruf dann https://cloud.DEINE_DOMAIN auf. Traefik holt beim ersten Zugriff das Zertifikat (kann ein paar Sekunden dauern). Weil wir Datenbank und Redis schon per Umgebungsvariablen konfiguriert haben, erkennt Nextcloud das automatisch und fragt nur noch nach einem Administrationskonto:

Vergib einen Admin-Namen und ein starkes Passwort und klick auf Installieren. Nextcloud richtet die Instanz ein – danach landest du auf der Anmeldeseite:

Nach dem Login begrüßt dich das Dashboard, und unter Dateien findest du deine Cloud mit ein paar Beispieldateien:

Schritt 5: Hintergrund-Jobs (Cron) einrichten

Nextcloud muss regelmäßig Aufgaben erledigen (Aufräumen, Benachrichtigungen, Vorschaubilder). Standardmäßig passiert das per „AJAX" bei jedem Seitenaufruf – das ist unzuverlässig. Der empfohlene Weg ist ein Cron-Sidecar: ein zweiter Container mit demselben Image, der nur cron.php ausführt. Ergänze in der compose.yaml einen Service:

  nc-cron:
    image: nextcloud:34-apache
    container_name: nc-cron
    entrypoint: /cron.sh
    depends_on:
      nc-db:
        condition: service_healthy
    volumes:
      - nc_html:/var/www/html
    networks: [default]
    restart: unless-stopped

Der Sidecar teilt sich das nc_html-Volume mit der App und führt die Jobs alle fünf Minuten aus. Übernimm die Änderung und stell den Modus in Nextcloud auf „Cron":

docker compose up -d
docker exec -u www-data nc-app php occ background:cron

Unter Verwaltung → Grundeinstellungen sollte jetzt „Cron" aktiv sein.

docker exec -u www-data nc-app php occ db:add-missing-indices
docker exec -u www-data nc-app php occ config:system:set default_phone_region --value=DE

Schritt 6: Die Clients verbinden

Jetzt der eigentliche Nutzen. Es gibt drei Wege, deine Cloud zu benutzen:

1. Desktop-Sync-Client (Windows/macOS/Linux): Installiere den „Nextcloud Desktop"- Client, gib als Server-Adresse https://cloud.DEINE_DOMAIN ein, melde dich an und wähle einen lokalen Ordner. Dateien werden wie bei Dropbox synchronisiert. Mit den virtuellen Dateien (Windows/macOS) belegen sie erst dann Platz auf der Platte, wenn du sie öffnest – praktisch, wenn deine Cloud größer ist als die lokale Festplatte.
2. Handy-App (Android/iOS): die offizielle Nextcloud-App, gleiche Server-Adresse. Ideal für den automatischen Foto-Upload vom Smartphone.
3. Kalender & Kontakte: In den Systemeinstellungen deines Geräts ein CalDAV-/ CardDAV-Konto mit der Adresse https://cloud.DEINE_DOMAIN anlegen – dank der .well-known-Middleware aus Schritt 3 funktioniert die automatische Erkennung.

Funktionen wie Kalender, Kontakte oder Mail sind eigene Apps, die du unter Verwaltung → Apps mit einem Klick nachinstallierst – Nextcloud ist also erweiterbar, ohne dass du am Server etwas anfassen musst.

Wenn es nicht funktioniert

Symptom: „Zugriff über eine nicht vertrauenswürdige Domäne" statt der Login-Seite.

Ursache & Lösung: Deine Domain steht nicht in trusted_domains. Prüfe NEXTCLOUD_TRUSTED_DOMAINS in der Compose-Datei. Nachträglich setzen geht per occ: docker exec -u www-data nc-app php occ config:system:set trusted_domains 1 --value=cloud.DEINE_DOMAIN.

Symptom: Der Sicherheits-Check meldet „Your web server is not set up properly to resolve .well-known/caldav".

Ursache & Lösung: Der CalDAV/CardDAV-Redirect greift nicht. Kontrolliere die nc-dav-Middleware-Labels (Schritt 3) und dass der Router sie über ...routers.nc.middlewares=nc-dav einbindet. Das Regex muss die volle https://…-URL matchen – redirectregex prüft die komplette URL, nicht nur den Pfad.

Symptom: Warnung „The ‘Strict-Transport-Security’ HTTP header is not set".

Ursache & Lösung: Der HSTS-Header fehlt. Setz ihn als Traefik-Middleware und häng sie an den Router: traefik.http.middlewares.nc-secure.headers.stsSeconds=15552000. Häng sie zusätzlich zur nc-dav-Middleware an den Router (...routers.nc.middlewares=nc-dav,nc-secure). Der Header muss vom Proxy kommen, nicht von Nextcloud. In Teil 2 richten wir genau diese nc-secure-Middleware vollständig ein (inklusive includeSubdomains).

Symptom: Große Uploads brechen ab oder enden mit einem Timeout / „413".

Ursache & Lösung: Das PHP-Limit ist zu klein. Erhöhe PHP_UPLOAD_LIMIT und PHP_MEMORY_LIMIT (Schritt 3) und starte den Container neu. In seltenen Fällen greifen diese Variablen nicht – dann ein eigenes php.ini-Snippet ins Image mounten.

Symptom: Beim ersten Start bricht die Installation mit „MySQL server has gone away" oder „Connection refused" ab.

Ursache & Lösung: Der App-Container war schneller als die Datenbank. Genau dagegen ist der healthcheck mit depends_on: condition: service_healthy da – prüfe, dass beide in deiner Compose-Datei vorhanden sind, und starte mit docker compose up -d neu.

Wartung & Backups

• Backups sind bei einer Cloud Pflicht. Ein konsistentes Backup braucht drei Dinge: die Datenbank (MariaDB-Dump), das Datenverzeichnis (deine Dateien) und die Konfiguration (config.php). Versetze Nextcloud vor dem Backup kurz in den Wartungsmodus, damit Datenbank und Dateien zueinander passen:

  Terminal

  docker exec -u www-data nc-app php occ maintenance:mode --on
  docker exec nc-db mariadb-dump -u root -pEIN_STARKES_ROOT_PASSWORT nextcloud > nextcloud-db.sql
  docker exec -u www-data nc-app php occ maintenance:mode --off

  Sichere den Dump zusammen mit dem nc_html-Volume verschlüsselt und off-site mit Restic – das rohe nc_db-Volume musst du dank des Dumps nicht zusätzlich sichern. Im nc_html-Volume stecken sowohl der Programmcode und die config.php als auch – unter data/ – deine eigentlichen Nutzerdateien. Wächst deine Cloud stark, kannst du dieses data/-Verzeichnis später auf ein eigenes, größeres Volume auslagern; fürs erste reicht ein Volume für alles.

• Updates: immer nur eine Hauptversion pro Schritt. Von 34 auf 35, nie direkt auf 36. Setz den Image-Tag hoch (nextcloud:35-apache), dann docker compose pull und docker compose up -d. Der Container führt das nötige occ upgrade beim Start automatisch aus. Vorher immer ein Backup anlegen. Den Cron-Sidecar auf dieselbe Version heben.

• Sicherheit prüfen. Lass nach dem Aufsetzen den offiziellen Nextcloud Security Scan gegen deine Domain laufen (Ziel: Note A) und arbeite die Warnungen aus der Admin-Übersicht ab. Die Übersicht unter Verwaltung → Übersicht führt automatische Prüfungen durch und zeigt genau, was noch fehlt. Halte Nextcloud aktuell – Sicherheitslücken werden zeitnah geschlossen, aber nur, wenn du updatest.

• Ehrlich zum Aufwand: Eine selbst gehostete Cloud will gepflegt werden. Rechne mit einem Update-Durchgang etwa monatlich und einem regelmäßigen Blick in die Admin-Übersicht. Dafür gehören die Daten dann wirklich dir.

Was bauen wir?

Am Ende läuft Uptime Kuma 2.4 unter https://status.DEINE_DOMAIN, abgesichert über Traefik mit automatischem HTTPS. Du hast den ersten Monitor eingerichtet (der prüft im Minutentakt, ob ein Dienst antwortet), eine Benachrichtigung verbunden und optional eine öffentliche Status-Seite. Zum ersten Mal binden wir dabei einen Dienst an, der nicht auf Port 80 lauscht – ein wichtiges Detail für alle folgenden Apps.

Voraussetzungen

• Ein laufender Traefik-Reverse-Proxy samt proxy-Netzwerk und funktionierendem Let’s-Encrypt-Resolver le
• Ein DNS-Record status.DEINE_DOMAIN, der auf den Server zeigt

Schritt für Schritt

Schritt 1: Die compose.yaml

Eigener Ordner, eigene Datei:

mkdir -p ~/uptime-kuma && cd ~/uptime-kuma

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    volumes:
      - kuma-data:/app/data
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.kuma.rule=Host(`status.DEINE_DOMAIN`)"
      - "traefik.http.routers.kuma.entrypoints=websecure"
      - "traefik.http.routers.kuma.tls.certresolver=le"
      - "traefik.http.services.kuma.loadbalancer.server.port=3001"
    restart: unless-stopped

volumes:
  kuma-data:

networks:
  proxy:
    external: true

Das kennst du aus dem Traefik-Tutorial – bis auf eine neue, entscheidende Zeile:

      - "traefik.http.services.kuma.loadbalancer.server.port=3001"

Uptime Kuma lauscht intern auf Port 3001, nicht auf 80. Diese Zeile sagt Traefik, an welchen Port es die Anfragen weiterreichen soll. Ohne sie rät Traefik falsch und du bekommst einen Bad Gateway. Merke dir das Label – jede App, die nicht auf Port 80 läuft, braucht es.

Der Rest ist das bekannte Muster: kein ports: (nur über Traefik erreichbar), proxy-Netzwerk, Named Volume für die Daten.

Schritt 2: Starten und ersten Login

docker compose up -d
docker compose logs -f uptime-kuma

Wenn Kuma bereit ist, endet das Log mit dieser Zeile – ab hier nimmt der Dienst Anfragen an (Strg+C beendet nur das Mitlesen):

[SERVER] INFO: Welcome to Uptime Kuma
[SERVER] INFO: Uptime Kuma Version: 2.4.0
[SETUP-DATABASE] INFO: Listening on:
[SETUP-DATABASE] INFO: -  http://localhost:3001

Beim ersten Start legt Kuma seine Datenbank im Volume an – das dauert einige Sekunden. Ruf dann https://status.DEINE_DOMAIN im Browser auf. Uptime Kuma 2.x fragt zuerst die Datenbank ab – für ein Setup wie unseres ist SQLite die richtige, einfachste Wahl (auswählen, auf Weiter klicken). Direkt danach legst du das Admin-Konto an (Benutzername + starkes Passwort).

Schritt 3: Den ersten Monitor anlegen

Ein Monitor ist eine wiederkehrende Prüfung. Klicke auf Neuen Monitor hinzufügen und lege einen für Traefik selbst an:

• Monitortyp: HTTP(s)
• Freundlicher Name: Traefik Dashboard
• URL: https://traefik.DEINE_DOMAIN
• Prüfintervall: 60 Sekunden
• Authentifizierung: Das Traefik-Dashboard ist per Basic-Auth geschützt (Schritt 7 des Traefik-Tutorials) – wähle deshalb unten HTTP Basic Auth als Authentifizierungsmethode und trage Benutzer und Passwort ein. Ohne Zugangsdaten bekommt Kuma nur 401 und meldet den Monitor als Down.

Speichern – nach wenigen Sekunden steht der Monitor auf Online (grün) und zeigt die Antwortzeit.

Neben dem einfachen HTTP(s)-Check lohnt es sich, den passenden Monitortyp zu wählen:

• HTTP(s) – Keyword: prüft zusätzlich, ob ein bestimmtes Wort im Antworttext steht. So erkennst du „Server antwortet zwar, zeigt aber eine Fehlerseite".
• TCP-Port: für Dienste ohne Web-Oberfläche (z. B. eine Datenbank, ein SSH-Port). Prüft nur, ob der Port offen ist.
• Ping: einfachster Erreichbarkeitstest per ICMP.
• Docker-Container: prüft direkt den Container-Status über den Docker-Socket – praktisch für interne Dienste ohne eigene Domain.
• Push: hier ruft der überwachte Dienst Kuma regelmäßig an. Ideal für Cronjobs und Backups: meldet sich das Skript nicht rechtzeitig, schlägt Kuma Alarm („Dead man’s switch").

Lege für jeden wichtigen Dienst den passenden Monitor an.

Beim HTTP(s)-Monitor lohnt sich zusätzlich die Option „Zertifikatsablauf-Benachrichtigung": Kuma warnt dann rechtzeitig, bevor ein TLS-Zertifikat ausläuft. Bei Diensten hinter Traefik erneuert Let’s Encrypt zwar automatisch – aber genau dieser Automatismus fällt gelegentlich leise aus (ein DNS-Record wird geändert, Port 80 versehentlich zugemacht). Der Monitor ist dein Sicherheitsnetz und meldet sich, solange noch Tage zum Reparieren bleiben, statt dass Besucher plötzlich vor einer Zertifikatswarnung stehen.

Schritt 4: Benachrichtigungen einrichten (E-Mail und Telegram)

Ein Monitor ohne Alarm ist nur ein hübsches Diagramm. Unter Einstellungen → Benachrichtigungen → Benachrichtigung einrichten legst du einen Kanal an. Uptime Kuma unterstützt über 90 – wir richten die zwei häufigsten komplett ein: E-Mail für die klassische Nachricht und Telegram für Push direkt aufs Handy.

E-Mail (SMTP)

Wähle als Benachrichtigungsdienst „E-Mail (SMTP)" und trage die Daten deines Mailanbieters ein:

• Hostname / Port: z. B. smtp.DEIN_ANBIETER.de und 587
• Sicherheit: STARTTLS (Port 587) oder TLS/SSL (Port 465)
• Benutzername / Passwort: deine SMTP-Zugangsdaten
• Absender- / Empfänger-Adresse: von welcher Adresse die Warnung kommt und an welche sie geschickt wird

Klick auf Test – innerhalb weniger Sekunden landet eine Testnachricht im Postfach. Erst wenn die wirklich ankommt, stimmen Zugangsdaten und Port. Speichern nicht vergessen.

Telegram

Telegram ist ideal für sofortige Push-Alarme aufs Handy – ohne eigenen Mailserver. Du brauchst zwei Angaben:

1. Bot-Token: Schreib in Telegram @BotFather an, sende /newbot, vergib einen Namen – BotFather antwortet mit dem Token.
2. Chat-ID: Schreib deinem neuen Bot eine beliebige Nachricht, ruf dann https://api.telegram.org/bot<DEIN_TOKEN>/getUpdates im Browser auf und lies die chat.id aus der Antwort.

Trage Token und Chat-ID in die Telegram-Benachrichtigung ein (Uptime Kuma verlinkt beide Hilfen direkt im Dialog) und klick Test – die Nachricht sollte sofort im Chat erscheinen.

Willst du Push-Nachrichten komplett in Eigenregie (ohne Telegram-Server), kommt später ntfy dazu – selbst gehostet, mit eigenem Rezept in der Serie.

Schritt 5: Eine öffentliche Status-Seite (optional)

Kuma kann eine Status-Seite veröffentlichen, auf der Besucher sehen, ob deine Dienste laufen. So gehst du vor:

1. Statusseiten → Neue Status-Seite, dann Name (z. B. „Serverküche Status") und Slug (die URL, z. B. serverkueche) vergeben und auf Weiter klicken.
2. Im Editor Gruppe hinzufügen (z. B. „Dienste"), darunter über das Auswahlfeld die gewünschten Monitore hinzufügen.
3. Oben rechts Speichern – fertig. Öffentlich erreichbar ist die Seite dann unter https://status.DEINE_DOMAIN/status/serverkueche.

Nimm nur auf, was wirklich jeder sehen darf – interne Dienste besser weglassen.

Schritt 6: Fehlalarme vermeiden – das Alarm-Verhalten feinjustieren

Ein Monitor, der bei jedem kurzen Netzwerk-Schluckauf Alarm schlägt, wird schnell ignoriert – und dann verpasst du den echten Ausfall. Im Monitor-Formular stellst du das Verhalten passend ein:

• Wiederholungen (Retries): Erst nach n fehlgeschlagenen Prüfungen gilt der Dienst als „Down". 2–3 filtert einzelne Aussetzer heraus, ohne echte Ausfälle lange zu verschleiern.
• Heartbeat-Intervall bei Ausfall: Kuma darf im Fehlerfall häufiger prüfen (z. B. alle 20 Sekunden), um die Erholung schnell zu erkennen.
• Erneut benachrichtigen: Kuma kann dich alle x Minuten erinnern, solange ein Dienst down ist – nützlich, damit ein Ausfall nachts nicht in einer einzigen Mail untergeht.

Schritt 7: Cronjobs überwachen mit einem Push-Monitor

Klassische Monitore prüfen von außen, ob ein Dienst antwortet. Für Dinge, die still im Hintergrund laufen – ein nächtliches Backup, ein Sync-Skript, ein Cronjob – dreht der Push-Monitor das Prinzip um: Nicht Kuma fragt an, sondern dein Skript meldet sich. Bleibt die Meldung aus, schlägt Kuma Alarm – der klassische „Dead man’s switch".

Lege einen Monitor vom Typ Push an. Kuma zeigt dir dann eine eindeutige Push-URL:

https://status.DEINE_DOMAIN/api/push/DEIN_TOKEN?status=up&msg=OK&ping=

Diese URL rufst du am Ende deines Skripts auf – zum Beispiel nach einem erfolgreich durchgelaufenen Backup:

# ... dein Backup-Befehl ...
curl -fsS "https://status.DEINE_DOMAIN/api/push/DEIN_TOKEN?status=up&msg=Backup+OK" > /dev/null

Stell das Prüfintervall in Kuma etwas großzügiger ein als deinen Cron-Takt (läuft das Backup stündlich, gib Kuma z. B. 90 Minuten Toleranz). Kommt in dieser Zeit kein curl, geht der Monitor auf Down und du wirst benachrichtigt – du erfährst also von einem nicht gelaufenen Backup, nicht erst, wenn du es dringend brauchst.

Schritt 8: Den Admin-Login mit 2FA absichern

Dein Kuma-Login schützt den Zugang zu allen Monitoren, den hinterlegten Benachrichtigungs-Zugangsdaten und der Status-Seiten-Konfiguration – und er hängt öffentlich im Netz. Schalte deshalb Zwei-Faktor-Authentifizierung ein: unter Einstellungen → Sicherheit → Zwei-Faktor-Authentifizierung. Kuma zeigt einen QR-Code, den du mit einer Authenticator-App (z. B. Aegis oder 2FAS) scannst; zum Aktivieren gibst du einmal den erzeugten Code ein.

Wenn es nicht funktioniert

Symptom: Bad Gateway (502) beim Aufruf von status.DEINE_DOMAIN.

Ursache & Lösung: Fast immer fehlt das Port-Label traefik.http.services.kuma.loadbalancer.server.port=3001 oder es steht ein falscher Port drin. Traefik erreicht den Container dann zwar, klopft aber am falschen Port an. Label prüfen und docker compose up -d erneut ausführen.

Symptom: 404 page not found statt Kuma.

Ursache & Lösung: Wie bei jeder App hinter Traefik: traefik.enable=true gesetzt? Container im proxy-Netzwerk? Stimmt die Domain in der Host(...)-Regel und zeigt der DNS-Record status.DEINE_DOMAIN auf den Server? Das Traefik-Dashboard zeigt unter „HTTP Routers", ob kuma registriert ist.

Symptom: Die Oberfläche lädt, aber die Live-Aktualisierung ruckelt / bricht ab.

Ursache & Lösung: Kuma nutzt WebSockets. Traefik leitet die standardmäßig korrekt weiter – tritt das Problem trotzdem auf, liegt es meist an einem davorgeschalteten CDN/Proxy (z. B. Cloudflare im „Proxy"-Modus), der WebSockets blockt. Für den Direktbetrieb hinter Traefik ist keine Zusatzkonfiguration nötig.

Symptom: Nach einem Neuaufsetzen sind alle Monitore weg.

Ursache & Lösung: Das kuma-data-Volume wurde gelöscht (z. B. durch docker compose down -v). Alle Konfiguration und Historie liegt allein in diesem Volume – deshalb steht es im nächsten Abschnitt ganz oben.

Wartung & Backups

• Sichern: Das komplette Herz von Kuma ist das Volume kuma-data (eine SQLite-Datenbank). Sichere es regelmäßig – ist es weg, sind alle Monitore und die Historie weg. Das Off-Site-Backup dafür bauen wir im Restic-Tutorial.
• Updates: Tag :2 bleibt bei der 2.x-Reihe und bringt Fehlerbehebungen mit docker compose pull && docker compose up -d. Vor einem Sprung auf eine neue Hauptversion (z. B. später :3) die Release-Notes lesen und vorher das Volume sichern.
• Von 1.x kommend? Der Wechsel auf :2 migriert die SQLite-Datenbank beim ersten Start automatisch – das kann einen Moment dauern, und ein Zurück auf :1 ist danach nicht vorgesehen. Sichere deshalb vorher das kuma-data-Volume, dann bist du auf der sicheren Seite. Neu-Installationen (wie oben) betrifft das nicht.
• Ehrliche Einschränkung: Ein Monitor, der auf demselben Server läuft wie die überwachten Dienste, kann dich nicht warnen, wenn der ganze Server ausfällt – dann ist auch Kuma offline. Ergänze für den Ernstfall einen externen Wächter. Zwei günstige Wege: ein zweites Uptime Kuma auf einem kleinen Server (oder zu Hause), das nur diese Instanz per HTTP überwacht – oder ein kostenloser externer Ping-Dienst, der deine öffentliche Status-Seite anpingt. So bekommst du auch dann eine Meldung, wenn der ganze Host weg ist – der einzige Fall, den ein lokaler Monitor prinzipbedingt nicht abdecken kann.

Damit hast du das App-Muster verinnerlicht und überwachst ab sofort alles, was du hinter Traefik hängst. Was jede weitere App voraussetzt, sind verschlüsselte Off-Site-Backups mit Restic – damit deine Daten einen Servercrash überleben.

Was bauen wir?

Am Ende läuft Vaultwarden 1.36 in einem Container hinter deinem Traefik-Proxy, erreichbar unter https://vault.DEINE_DOMAIN mit gültigem HTTPS-Zertifikat. Vaultwarden ist eine schlanke, in Rust geschriebene Neuimplementierung des Bitwarden-Servers: API-kompatibel, aber sparsam genug, um auf einem kleinen VPS zu laufen. Du verbindest die offiziellen Bitwarden-Clients (Browser-Erweiterung, Handy-App, Desktop) mit deinem Server, legst deine Zugangsdaten ab – Ende-zu-Ende verschlüsselt – und verwaltest den Dienst über ein abgesichertes Admin-Panel.

Deine Passwörter liegen damit auf deinem Server, in deinem Land, unter deinem Backup – und du zahlst keine Abo-Gebühr für Funktionen wie 2FA oder Attachments.

Voraussetzungen

• Ein laufender Traefik-Reverse-Proxy mit dem gemeinsamen proxy-Netzwerk und dem Let’s-Encrypt-Resolver le – genau das Setup aus dem Tutorial Reverse Proxy mit Traefik. Ohne Traefik funktioniert dieses Rezept nicht: Vaultwarden verlangt HTTPS.
• Eine Subdomain, z. B. vault.DEINE_DOMAIN, deren DNS-Record (A/AAAA) auf deine Server-IP zeigt – siehe Domain mit Server verbinden.
• Ein funktionierendes Backup deines Servers. Ein Passwortmanager ist der Ort, an dem Datenverlust am meisten wehtut – richte, falls noch nicht geschehen, zuerst Backups mit Restic ein.

Willst du später mehrere Dienste kombinieren, hilft der Server-Rechner bei der passenden Server-Größe.

Schritt für Schritt

Schritt 1: Den ADMIN_TOKEN erzeugen

Vaultwarden hat ein Admin-Panel unter /admin. Zugriff darauf schützt ein ADMIN_TOKEN. Den solltest du nicht im Klartext hinterlegen, sondern als Hash – dann steht dein Panel-Passwort nirgends lesbar in der Compose-Datei.

Vaultwarden bringt dafür einen eigenen Befehl mit. Wir lassen ihn kurz in einem Wegwerf-Container laufen:

docker run --rm -it vaultwarden/server:1.36.0 /vaultwarden hash --preset owasp

Der Befehl fragt dich zweimal nach einem Passwort (Eingabe bleibt unsichtbar) und gibt dann einen Argon2id-Hash aus – eine lange Zeichenkette, die so beginnt:

Generate an Argon2id PHC string using the 'owasp' preset.

Password:
Confirm Password:

ADMIN_TOKEN='$argon2id$v=19$m=19456,t=2,p=1$FkxFEQ64Wy4zlQOWMI1fJ...$TxULe6MSND3By6GPVPKB1...'

Kopiere die komplette Zeichenkette zwischen den Anführungszeichen (inklusive der $argon2id$…-Teile) heraus – die brauchst du gleich. Das Passwort, das du hier eingegeben hast, ist dein Admin-Panel-Passwort; leg es im Passwortmanager ab (fürs Erste noch im alten).

Schritt 2: Die compose.yaml anlegen

Leg einen eigenen Ordner an und wechsle hinein:

mkdir -p ~/vaultwarden && cd ~/vaultwarden

Erstelle die compose.yaml. Ersetze vault.DEINE_DOMAIN durch deine echte Subdomain und den ADMIN_TOKEN durch den Hash aus Schritt 1:

services:
  vaultwarden:
    image: vaultwarden/server:1.36.0
    volumes:
      - ./vw-data:/data
    environment:
      DOMAIN: "https://vault.DEINE_DOMAIN"
      SIGNUPS_ALLOWED: "true"
      ADMIN_TOKEN: "$$argon2id$$v=19$$m=19456,t=2,p=1$$FkxFE...$$TxULe..."
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.vaultwarden.rule=Host(`vault.DEINE_DOMAIN`)"
      - "traefik.http.routers.vaultwarden.entrypoints=websecure"
      - "traefik.http.routers.vaultwarden.tls.certresolver=le"
      - "traefik.http.services.vaultwarden.loadbalancer.server.port=80"
    networks:
      - proxy
    restart: unless-stopped

networks:
  proxy:
    external: true

Die wichtigsten Zeilen im Detail:

• image: vaultwarden/server:1.36.0 – wir pinnen die Version bewusst fest, statt latest zu nehmen. So aktualisierst du kontrolliert (siehe „Wartung"). Für ein noch kleineres Image gibt es auch :1.36.0-alpine.
• volumes: ./vw-data:/data – hier liegen deine Datenbank (db.sqlite3), die Verschlüsselungs-Keys und die Attachments. Dieses Volume ist Pflicht. Ohne Volume verweigert Vaultwarden absichtlich den Start, damit du deine Daten nicht in einem flüchtigen Container verlierst.
• DOMAIN – die vollständige HTTPS-URL. Vaultwarden braucht sie u. a. für WebAuthn/ 2FA und Einladungslinks. Muss exakt zu deiner Router-Regel passen.
• SIGNUPS_ALLOWED: "true" – erlaubt vorerst die Registrierung, damit du dein erstes Konto anlegen kannst. Das drehen wir gleich wieder ab.
• ADMIN_TOKEN – dein Hash aus Schritt 1. Wichtig: In einer Compose-Datei muss jedes Dollarzeichen verdoppelt werden ($ → $$), sonst versucht Compose, es als Variable zu interpretieren. Aus $argon2id$… wird also $$argon2id$$….
• loadbalancer.server.port=80 – Vaultwarden lauscht im Container auf Port 80. Diese Zeile sagt Traefik explizit, wohin es intern weiterleiten soll, statt den Zielport aus dem Image raten zu lassen – dasselbe Muster wie bei jeder App hinter Traefik.
• Kein ports: – wie bei jeder App hinter Traefik ist Vaultwarden nur über den Proxy erreichbar, niemals direkt von außen.

Schritt 3: Starten und den ersten Aufruf

Starte den Container:

docker compose up -d

Beim ersten Start legt Vaultwarden das Datenverzeichnis an und initialisiert die Datenbank. Wirf einen Blick ins Log:

docker compose logs -f vaultwarden

Du solltest am Ende diese Zeile sehen – sie bestätigt, dass der Dienst läuft:

[INFO] Rocket has launched from http://0.0.0.0:80

Mit Strg+C verlässt du die Log-Ansicht wieder (der Container läuft weiter). Ruf jetzt https://vault.DEINE_DOMAIN im Browser auf. Traefik holt beim ersten Zugriff das Let’s-Encrypt-Zertifikat – das kann ein paar Sekunden dauern. Danach erscheint die Bitwarden-Web-Oberfläche.

Klick auf Konto erstellen und leg dein erstes Konto an – mit deiner E-Mail-Adresse und einem Namen:

Im nächsten Schritt legst du dein Master-Passwort fest. Das ist der eine Schlüssel, der deinen gesamten Tresor entsperrt:

Schritt 4: Die Registrierung wieder schließen

Sobald dein Konto steht, willst du verhindern, dass Fremde sich ebenfalls registrieren können – dein Vaultwarden hängt schließlich offen im Internet. Setz SIGNUPS_ALLOWED in der compose.yaml auf false:

    environment:
      DOMAIN: "https://vault.DEINE_DOMAIN"
      SIGNUPS_ALLOWED: "false"
      ADMIN_TOKEN: "$$argon2id$$..."

Und übernimm die Änderung:

docker compose up -d

Compose erkennt die geänderte Umgebungsvariable und startet den Container neu. Ab jetzt weist die Anmeldeseite neue Registrierungen ab. Weitere Nutzer (z. B. für die Familie) lädst du bei Bedarf gezielt über das Admin-Panel ein – dazu gleich mehr.

Schritt 5: Das Admin-Panel

Ruf https://vault.DEINE_DOMAIN/admin auf und melde dich mit dem Passwort an, das du in Schritt 1 beim Erzeugen des Hashes eingegeben hast (nicht mit dem Hash selbst). Du landest in der Verwaltungsoberfläche:

Hier steuerst du den Dienst zentral:

• Users – vorhandene Nutzer einsehen, neue einladen (auch bei SIGNUPS_ALLOWED=false), Konten deaktivieren.
• Settings → SMTP Email Settings – trag hier die Zugangsdaten deines Mail-Servers ein, damit Vaultwarden Einladungen und 2FA-Codes per Mail verschicken kann. Ohne SMTP funktioniert die Einladung per Link zwar auch, aber E-Mail-basierte 2FA nicht.
• Diagnostics – zeigt dir, ob deine DOMAIN korrekt gesetzt ist und ob Vaultwarden von außen erreichbar ist – praktisch bei der Fehlersuche.

Schritt 6: Die Clients verbinden

Jetzt kommt der eigentliche Nutzen. Installiere die offizielle Bitwarden-App oder -Browser-Erweiterung (aus dem jeweiligen App- bzw. Add-on-Store). Bevor du dich anmeldest, stellst du den Server um:

1. Öffne in der App/Erweiterung noch vor dem Login die Einstellungen für die selbst gehostete Umgebung (Zahnrad-Symbol bzw. „Region: Selbst gehostet").
2. Trag als Server-URL https://vault.DEINE_DOMAIN ein und speichere.
3. Melde dich jetzt mit deiner E-Mail und deinem Master-Passwort an – die App spricht ab sofort mit deinem Server.

Das Schöne: Es sind dieselben ausgereiften Clients wie beim kommerziellen Bitwarden. Autofill, Passwort-Generator, sichere Notizen, Attachments und 2FA-Speicherung funktionieren genauso – nur liegen die Daten auf deinem Server.

Bestehende Passwörter importieren: Wechselst du von einem anderen Manager (oder dem Browser-Passwortspeicher), musst du nicht alles abtippen. Exportiere dort deine Einträge als CSV oder JSON und importiere sie über die Web-Oberfläche unter Werkzeuge → Daten importieren. Vaultwarden versteht die Exportformate der gängigen Manager (KeePass, LastPass, 1Password, Chrome/Firefox u. a.) direkt.

Wenn es nicht funktioniert

Symptom: Der Container startet nicht, das Log sagt sinngemäß Running without a persistent volume is not recommended.

Ursache & Lösung: Es fehlt das volumes:-Mapping. Vaultwarden verweigert absichtlich den Start ohne Datenverzeichnis, damit deine Passwörter nicht in einem flüchtigen Container landen. Ergänze ./vw-data:/data wie in Schritt 2 und starte neu.

Symptom: Die Web-Oberfläche zeigt „You need to enable HTTPS!" oder der Login scheitert mit Krypto-Fehlern.

Ursache & Lösung: Vaultwarden nutzt die Web-Crypto-API des Browsers, die nur in einem sicheren Kontext (echtes HTTPS) verfügbar ist. Du hast die Seite über http:// oder mit ungültigem Zertifikat aufgerufen. Stell sicher, dass Traefik ein gültiges Let’s-Encrypt-Zertifikat geholt hat (Traefik-Log prüfen) und du die Seite über https:// erreichst. Die DOMAIN-Variable muss ebenfalls mit https:// beginnen.

Symptom: Das Admin-Panel weist dein Passwort ab, obwohl es stimmt.

Ursache & Lösung: Vermutlich sind die Dollarzeichen im ADMIN_TOKEN nicht verdoppelt. In der compose.yaml muss aus jedem $ ein $$ werden. Prüfe mit docker compose config, wie der Token tatsächlich ankommt (Compose zeigt dort den aufgelösten Wert). Denk auch daran: Beim Login gibst du das Passwort ein, nicht den Hash.

Symptom: Die Handy-App findet den Server nicht oder meldet „Server-URL ungültig".

Ursache & Lösung: Die Server-URL muss die vollständige https://-Adresse ohne abschließenden Pfad sein (https://vault.DEINE_DOMAIN). Prüfe außerdem, ob die Domain von außen per Browser erreichbar ist und das Zertifikat gültig ist – Apps sind bei Zertifikatsfehlern strenger als Browser.

Symptom: Trotz SIGNUPS_ALLOWED=false konnte sich jemand registrieren.

Ursache & Lösung: Wahrscheinlich wurde die Einstellung im Admin-Panel gesetzt und überschreibt die Umgebungsvariable, oder der Container wurde nach der Änderung nicht neu gestartet. Kontrolliere den Wert unter Settings → General settings im Panel und starte mit docker compose up -d neu.

Wartung & Backups

• Backups sind bei einem Passwortmanager nicht verhandelbar. Dein gesamter Tresor steckt im Verzeichnis vw-data/ (SQLite-Datenbank, Keys, Attachments). Sichere es verschlüsselt und off-site mit Restic – nimm den Ordner ~/vaultwarden/vw-data in deine Backup-Quellen auf. Für einen konsistenten Datenbank-Stand führst du vor dem Backup kurz docker compose stop aus oder nutzt die „Backup Database"-Funktion im Admin-Panel. Eine bloße Dateikopie bei laufendem Container kann dagegen einen inkonsistenten Stand erwischen (SQLite schreibt in WAL-Dateien) – bei einem Passwortmanager ist das kein Risiko wert.

• Updates kontrolliert einspielen. Weil wir die Version gepinnt haben, aktualisierst du bewusst: Vor dem Wechsel die Release-Notes lesen, dann den Tag in der compose.yaml erhöhen (z. B. auf die nächste 1.x) und neu ziehen:

  Terminal

  docker compose pull && docker compose up -d

  Prüfe danach im Log wieder die Rocket has launched-Zeile und teste einen Login.

• Registrierung geschlossen lassen. Kontrolliere gelegentlich, dass SIGNUPS_ALLOWED weiterhin false ist – neue Nutzer immer gezielt über das Admin-Panel einladen.

• ADMIN_TOKEN rotieren, wenn er kompromittiert sein könnte: neuen Hash mit dem hash-Befehl aus Schritt 1 erzeugen, in der compose.yaml ersetzen, neu starten.

• Master-Passwort niemals verlieren. Es gibt keine Wiederherstellung. Bei einem Team/Familien-Setup kann ein Notfall-Zugang (Emergency Access) sinnvoll sein – den richtest du pro Tresor in den Kontoeinstellungen ein.

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.