2FAuth als eigenen TOTP-Tresor per Docker installieren¶

Veröffentlicht am 22. August 2026 · Geschätzte Lesezeit: 4 Minuten

2FAuth verwaltet zeitbasierte Einmalcodes für Zwei-Faktor-Anmeldungen im eigenen Browser. Die Konten liegen verschlüsselt auf deinem Server statt ausschließlich auf einem einzelnen Telefon. Wegen der sensiblen Schlüssel solltest du für die sichere Einrichtung mit HTTPS etwa 30 Minuten einplanen.

Voraussetzungen

Ein Linux-Server mit Docker und Docker Compose
Eine eigene Domain oder Subdomain, zum Beispiel 2fa.example.de
Ein vorhandener HTTPS-Reverse-Proxy und passender DNS-Eintrag
Der Port 8000 im Heimnetz frei

1. Arbeitsordner vorbereiten¶

Erstelle auf dem Docker-Server den Projekt- und Datenordner:

mkdir -p ~/2fauth/data && cd ~/2fauth

2FAuth läuft im Container ohne Root-Rechte als Benutzer 1000:1000. Setze deshalb Besitzer und Zugriffsrechte des Datenordners passend:

sudo chown -R 1000:1000 data && chmod 700 data

2. Verschlüsselungsschlüssel erzeugen¶

Der folgende Befehl erzeugt lokal einen persönlichen Anwendungsschlüssel und schreibt ihn in app_key.txt. Der Wert wird nicht im Terminal oder in der Compose-Datei benötigt:

docker run --rm --entrypoint /usr/bin/php 2fauth/2fauth:latest artisan key:generate --show > app_key.txt

Schütze die Schlüsseldatei vor anderen Serverbenutzern:

chmod 600 app_key.txt

Schlüssel niemals verlieren oder veröffentlichen

Ohne diesen Schlüssel können verschlüsselte Inhalte nach einer Wiederherstellung unbrauchbar sein. Lege ihn nicht in Git ab und ändere ihn später nicht einfach.

3. Compose-Datei erstellen¶

Lege im Ordner ~/2fauth eine Datei namens compose.yaml an. Ersetze <2fauth-domain> durch deine vollständige HTTPS-Adresse ohne abschließenden Schrägstrich:

services:
  2fauth:
    image: 2fauth/2fauth:latest
    container_name: 2fauth
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      APP_URL: https://<2fauth-domain>
      APP_ENV: production
      APP_TIMEZONE: Europe/Berlin
      APP_KEY_FILE: /run/secrets/app_key
      LOG_LEVEL: notice
    volumes:
      - ./data:/2fauth
    secrets:
      - app_key

secrets:
  app_key:
    file: ./app_key.txt

Das Docker-Secret stellt den Schlüssel nur unter /run/secrets/app_key bereit. Datenbank, Symbole und Anwendungsdaten bleiben im lokalen Ordner data erhalten.

4. Container starten¶

Starte 2FAuth auf dem Docker-Server:

docker compose up -d

Prüfe anschließend den Zustand:

docker compose ps

Bei einem Startfehler zeigen die Protokolle die Ursache:

docker compose logs --tail=100 2fauth

5. HTTPS-Reverse-Proxy einrichten¶

Leite https://<2fauth-domain> im Reverse-Proxy an http://<server-ip>:8000 weiter. Ersetze <2fauth-domain> durch denselben Wert aus compose.yaml und <server-ip> durch die feste IP-Adresse des Docker-Servers. Aktiviere ein gültiges TLS-Zertifikat und erzwinge HTTPS.

TOTP-Geheimnisse nur über HTTPS

Leite Port 8000 nicht direkt im Router weiter. Kamera-Zugriff für QR-Codes und sichere Browserfunktionen benötigen HTTPS; ein VPN ist für den Zugriff von unterwegs zusätzlich sinnvoll.

6. Konto anlegen und absichern¶

Öffne https://<2fauth-domain> und lege dein Konto mit einem langen, einmaligen Passwort an. Aktiviere danach in den Sicherheitseinstellungen eine Passkey- oder WebAuthn-Anmeldung, wenn dein Browser und dein Sicherheitsschlüssel dies unterstützen.

Nicht im eigenen Tresor aussperren

Bewahre Wiederherstellungscodes wichtiger Dienste offline auf. Nutze nicht ausschließlich einen TOTP-Code aus 2FAuth, um genau diese 2FAuth-Installation oder deren einzigen Zugangsweg freizuschalten.

7. Erstes TOTP-Konto importieren¶

Füge zunächst nur ein unwichtiges Testkonto über dessen QR-Code oder manuellen Geheimschlüssel hinzu. Vergleiche den erzeugten Code mit deiner bisherigen Authenticator-App, bevor du die alte Kopie entfernst.

Ein TOTP-Code funktioniert nur bei korrekter Uhrzeit. Prüfe auf dem Docker-Server die Zeitsynchronisation:

timedatectl status

Steht dort nicht System clock synchronized: yes, korrigiere zuerst die Zeitsynchronisation des Hosts, bevor du weitere Konten überträgst.

8. Verschlüsseltes Backup erstellen¶

Stoppe 2FAuth kurz, damit die SQLite-Datenbank konsistent gesichert wird:

docker compose stop 2fauth

Archiviere Daten, Anwendungsschlüssel und Compose-Datei im Projektordner:

tar -czf 2fauth-backup-$(date +%F-%H%M).tar.gz data app_key.txt compose.yaml

Starte den Container anschließend wieder:

docker compose start 2fauth

Backup enthält die TOTP-Geheimnisse

Verschlüssele das Archiv und kopiere es auf ein getrenntes Gerät. Zusätzlich kannst du ausgewählte Konten in 2FAuth als JSON exportieren; auch dieser Export muss wie ein Passwort geschützt werden.

9. Typische Fehler beheben¶

Fehler zu APP_KEY: Prüfe, ob app_key.txt existiert, lesbar ist und nur APP_KEY_FILE, nicht zusätzlich APP_KEY, gesetzt wurde.
Datenbank kann nicht geschrieben werden: Kontrolliere Besitzer 1000:1000 und Rechte des Ordners data.
QR-Kamera funktioniert nicht: Öffne die Seite über die konfigurierte HTTPS-Domain, nicht über die unverschlüsselte Server-IP.
Codes werden abgelehnt: Prüfe Uhrzeit und NTP-Synchronisation von Server und Gerät.
Server ausgefallen: Nutze die offline verwahrten Wiederherstellungscodes und spiele erst danach das verschlüsselte Backup ein.

10. Quellen und Videos¶

Fertig¶

2FAuth läuft jetzt über HTTPS, liest den Anwendungsschlüssel aus einem Docker-Secret und speichert seine Daten dauerhaft. Prüfe mit einem Testkonto, ob derselbe TOTP-Code wie in deiner bisherigen App erscheint und nach einem Neustart weiterhin vorhanden ist.