Backups, Updates und Fehlersuche

Der Dienst backup sichert alle 24 Stunden (BACKUP_INTERVAL_HOURS) in den Ordner BACKUP_DIR:

• passbox-<zeit>.dump.age: die Datenbank, verschlüsselt mit Ihrem age-Schlüssel,
• blobs-<zeit>.tar.age: die Dateianhänge, noch einmal verschlüsselt,
• last-success: der Zeitpunkt des letzten vollständigen Backups. Überwachen Sie diese Datei.

Backups, die älter sind als BACKUP_KEEP_DAYS (Standard 14), löscht der Dienst. Ein Backup auf Abruf:

docker compose run --rm backup once

Die Backups enthalten alles, auch die Serverschlüssel in der Tabelle server_secrets. Ohne diese Tabelle könnten sich alle Nutzer nicht mehr anmelden, obwohl ihre Daten unversehrt wären.

Betreiben Sie die Datenbank ohne Docker Compose, sichern Sie mit pg_dump als Rolle passbox_migrator oder als Superuser. Die anderen Rollen sehen wegen Row Level Security nur einen Teil der Zeilen.

1. Passbox und Backups anhalten:

   sh

   docker compose stop passbox backup

2. Den Zeitpunkt des Backups wählen, etwa 20261025T030000Z aus backups/passbox-20261025T030000Z.dump.age.

3. Mit dem privaten Schlüssel wiederherstellen. Das ersetzt Datenbank und Anhänge:

   sh

   BACKUP_AGE_KEY_FILE=/pfad/zu/passbox-backup-key.txt \
     docker compose --profile restore run --rm restore 20261025T030000Z

4. Wieder starten. Dabei läuft zuerst migrate, ein älteres Backup wird also auf den aktuellen Stand gebracht:

   sh

   docker compose up -d

Testen Sie die Wiederherstellung ab und zu auf einem anderen Rechner: dieselbe Version auschecken, .env und ein Backup nach deploy/compose kopieren, docker compose up -d postgres starten und dann die Schritte 3 und 4 ausführen.

Machen Sie vor jedem Update ein Backup. Dann:

# neue Version in .env eintragen, etwa PASSBOX_IMAGE=ghcr.io/passboxnet/server:0.2.0
docker compose pull
docker compose up -d

docker compose up führt zuerst die Migrationen aus und startet dann Passbox neu. Caddy hält Anfragen während des Neustarts bis zu 15 Sekunden zurück.

Migrationen lassen sich nicht rückgängig machen. Um zu einer älteren Version zurückzukehren, stellen Sie das Backup von vor dem Update wieder her.

Mit mehreren Servern hintereinander setzen Sie PASSBOX_AUTO_MIGRATE=false und führen passbox-server migrate einmal vor dem Ausrollen aus. Neue Server melden sich auf /ready erst bereit, wenn die Datenbank ihre Migrationen hat.

Veröffentlichte Images sind mit cosign signiert und haben eine Stückliste (SBOM) und Herkunftsnachweise:

cosign verify ghcr.io/passboxnet/server:0.2.0 \
  --certificate-identity-regexp '^https://github\.com/passboxnet/server/\.github/workflows/images\.yml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
docker buildx imagetools inspect ghcr.io/passboxnet/server:0.2.0 --format '{{ json .SBOM }}'

Sie können das Image auch selbst bauen: docker compose build im Ordner deploy/compose.

• GET /health antwortet, solange der Prozess läuft.
• GET /ready antwortet mit 200 und der Version der Migrationen, wenn die Datenbank bereit ist, sonst mit 503.
• Mit PASSBOX_METRICS_BIND liefert ein eigener Port Metriken im Prometheus-Format: Anfragen nach Route und Status mit Antwortzeiten, Auslastung der Datenbankverbindungen und die Länge der Warteschlangen für E-Mails und Webhooks. Kontodaten enthalten die Metriken nicht. Halten Sie den Port trotzdem intern.
• Die Datei last-success im Backup-Ordner zeigt das letzte gelungene Backup.

Das Zertifikat wird nicht ausgestellt. Prüfen Sie, ob die DNS-Einträge auf den Server zeigen und die Ports 80 und 443 von außen erreichbar sind. Die Meldungen sehen Sie mit docker compose logs caddy.

Passbox startet nicht. docker compose logs migrate passbox zeigt den Grund. Häufig ist es ein Tippfehler in .env, eine ungültige SMTP-URL oder ein ungültiger Absender. Fehlt eine Pflichtvariable, nennt Docker Compose sie beim Start.

Die Datenbank meldet falsche Passwörter. Die Rollen und Passwörter entstehen nur beim allerersten Start mit leerem Datenverzeichnis. Haben Sie die Passwörter in .env später geändert, setzen Sie sie auch in der Datenbank:

docker compose exec postgres psql -U postgres -c "ALTER ROLE passbox_app PASSWORD '…'"

Rollen und Rechte stellen Sie jederzeit mit diesem Befehl wieder her, gefahrlos auch mehrmals:

docker compose exec postgres psql -U postgres -d passbox -v ON_ERROR_STOP=1 -f /passbox/roles.sql

Der Server warnt beim Start vor Row Level Security. Er läuft dann mit einer Rolle, die die Tabellen besitzt, oder mit einem Superuser. Nutzen Sie die drei getrennten Rollen.

E-Mails kommen nicht an. Öffnen Sie Administration → E-Mail. Dort stehen wartende und fehlgeschlagene E-Mails und der letzte Fehler. Testmail senden prüft die Einstellungen. Ohne PASSBOX_SMTP_URL landen E-Mails nur im Protokoll des Servers.

Alle Anmeldungen kommen von derselben IP oder werden zu früh begrenzt. Hinter einem Reverse Proxy muss PASSBOX_TRUST_PROXY=true gesetzt sein. Die Docker-Compose-Installation tut das schon.

Sicherheitsschlüssel funktionieren nach einem Umzug nicht mehr. Sicherheitsschlüssel und Passkeys für die Zwei-Faktor-Anmeldung gelten für den Hostnamen der Web-App. Nach einem Wechsel des Hostnamens melden sich Nutzer mit einem Wiederherstellungscode an und richten ihre Schlüssel neu ein.

Nach dem Wiederherstellen eines Backups kann sich niemand anmelden. Prüfen Sie, ob die Tabelle server_secrets im Backup enthalten war. Die Backups des Dienstes backup enthalten sie immer.