Datensicherung und Wiederherstellung

Eine Datensicherung (Backup) enthält die vollständige Datenbank und alle Dateien von heinzelhaus: Dokumente, Logos und die für die Datenübernahme hochgeladenen Sicherungen aus Karthago oder PowerHaus. Mit ihr nehmen Sie nach einem Defekt, einem Fehler oder einem Serverwechsel Ihre Arbeit wieder auf. Eine Platte, die mit dem Server stirbt, ist kein Backup. Diese Seite zeigt, wie Sie sichern, wohin Sie die Sicherungen bringen und wie Sie sie zurückspielen.

Alle Schritte in den Einstellungen brauchen die Rolle „Administrator“ und eine starke Anmeldung, siehe Anmeldesicherheit und Zwei-Faktor-Pflicht. Sie finden sie unter Seitenleiste → Verwaltung → „Einstellungen“ → Reiter „Backup“.

Was gesichert wird

In der Sicherung	Nicht in der Sicherung
Die vollständige Datenbank mit Konten, Rechten, Passkeys, Einstellungen und allen Buchungen	Die Datei .env mit den Kennwörtern und dem Schlüssel BETTER_AUTH_SECRET
Alle Dateien im Datenverzeichnis: Dokumente, Anhänge, Logos, hochgeladene Sicherungen aus der Datenübernahme	Die Datei docker-compose.override.yml
Pro Sicherung eine Anleitung LIESMICH.txt	Die Programmdateien. Die holt der Updater beim Update.
	Die Ordner backups, tmp und update im Datenverzeichnis

Achtung

Bewahren Sie eine Kopie der .env getrennt vom Server auf. Sie gehört nicht zur Sicherung. Der Schlüssel BETTER_AUTH_SECRET in ihr schützt die gespeicherten Zugangsdaten der Authenticator-Apps. Spielen Sie eine Sicherung auf einem neuen Server ein, der einen anderen Schlüssel hat, funktionieren eingerichtete Authenticator-Apps nicht mehr. Dann hilft nur der Notweg unter Anmeldesicherheit und Zwei-Faktor-Pflicht, oder Sie tragen den alten Schlüssel in die neue .env ein.

Gut zu wissen

Die Zugangsdaten für den E-Mail-Versand (SMTP-Passwort, Client-Secret) und für Schnittstellen wie Lexware Office liegen in der Datenbank und damit in jeder Sicherung. Sicherungen enthalten außerdem alle personenbezogenen Daten Ihrer Verwaltung. Verschlüsseln Sie Sicherungen, die den Server verlassen.

Vollständig oder inkrementell

Art	Was sie enthält
Vollständiges Backup	Die ganze Datenbank und alle Dateien
Inkrementelles Backup	Die ganze Datenbank, aber nur die Dateien, die sich seit dem letzten vollständigen Backup geändert haben

Das ist eine bewusste Entscheidung. Eine echte inkrementelle Sicherung der Datenbank brauchte eine lückenlose Kette von Protokolldateien. Reißt die Kette, ist alles danach unbrauchbar. Ein eigener, vollständiger Dump je Lauf ist bei der üblichen Datenmenge (wenige hundert Megabyte, komprimiert) günstig und robust: Jeder Stand lässt sich einzeln wiederherstellen. „Inkrementell“ bezieht sich auf die Dateiablage, die den Großteil des Speicherplatzes ausmacht.

Das erste Backup muss ein vollständiges sein. Davor ist „Inkrementelles Backup“ gesperrt, und der Hinweis „Zuerst ein vollständiges Backup“ erscheint.

Eine Sicherung von Hand erstellen

Damit Sie vor einem Update, vor einer Datenübernahme oder zwischendurch einen Stand sichern.

1. Öffnen Sie die Karte „Datensicherung“.
2. Wollen Sie die Sicherung verschlüsseln, schalten Sie „Dieses Backup mit einem Passwort verschlüsseln“ ein. Tragen Sie ein „Passwort“ mit mindestens 12 Zeichen ein, wiederholen Sie es unter „Passwort wiederholen“ und setzen Sie das Häkchen „Ich habe das Passwort sicher notiert und weiß, dass diese Sicherung ohne es nicht wiederherstellbar ist.“
3. Klicken Sie auf „Vollständiges Backup“ oder auf „Inkrementelles Backup“.
4. Warten Sie, bis „Vollständiges Backup erstellt.“ oder „Inkrementelles Backup erstellt.“ erscheint. Schlägt es fehl, steht dort „Backup fehlgeschlagen“ mit dem Grund.
5. Die Sicherung steht in der Karte „Vorhandene Sicherungen“. Die Tabelle zeigt „Zeitpunkt“, „Art“ (vollständig oder inkrementell, bei verschlüsselten mit dem Zusatz „Verschlüsselt“), die Größe von „Datenbank“ und „Dateien“ und den „Status“: „Fertig“, „Läuft“ oder „Fehler“. Neben den Knöpfen der Karte „Datensicherung“ steht, wie viele Sicherungen es gibt und wie viel Platz sie belegen.

Alle Benutzer erhalten eine Benachrichtigung: „Vollständiges Backup erstellt“ mit den Größen von Datenbank und Dateien oder „Backup fehlgeschlagen“ mit dem Grund.

Verschlüsselte Sicherungen

Eine verschlüsselte Sicherung schützt Ihre Daten dort, wo die Datei hinkommt: auf USB-Platten, in Cloud-Ablagen und bei einem Dienstleister. Gegen jemanden, der Zugriff auf den laufenden Server hat, schützt sie nicht, denn dort liegen die Daten ohnehin offen. Das Verfahren heißt scrypt für die Schlüsselableitung und AES-256-GCM für die Daten. Verschlüsselte Dateien tragen die Endung .enc. Auch das Verzeichnis der Dateien (manifest.json) wird mitverschlüsselt, weil Dokumentnamen personenbezogen sein können.

Achtung

Ohne das Passwort ist die Sicherung verloren. Das Passwort wird nirgends gespeichert, nicht in heinzelhaus und nicht in der Sicherung selbst. Es gibt keine Hintertür, keine Rücksetzung und keinen Weg über den Hersteller. Bewahren Sie es getrennt von der Sicherung auf, etwa in einem Passwortverwalter. Das Passwort gilt nur für dieses eine Backup und wird bei jedem Lauf neu abgefragt.

Die Anleitung LIESMICH.txt jeder Sicherung bleibt immer unverschlüsselt.

Automatisch sichern

Damit täglich gesichert wird, ohne dass jemand daran denken muss.

1. Öffnen Sie die Karte „Zeitplan“.
2. Schalten Sie „Automatische Backups aktivieren“ ein.
3. Wählen Sie die „Uhrzeit“ (Vorgabe 02:30), den Wochentag bei „Vollständig am“ (Vorgabe Sonntag) und bei „Vollständige Backups aufbewahren“ eine Zahl von 1 bis 52 (Vorgabe 4).
4. Klicken Sie auf „Zeitplan speichern“. Es erscheint „Backup-Zeitplan gespeichert.“

Am gewählten Wochentag läuft ein vollständiges, an allen anderen Tagen ein inkrementelles Backup. Fehlt ein vollständiges Backup als Basis, sichert der Hintergrunddienst ersatzweise vollständig.

Gut zu wissen

• Automatische Sicherungen sind immer unverschlüsselt. Sie liefen sonst nur mit einem gespeicherten Passwort, und ein gespeichertes Passwort neben der Sicherung wäre nur der Anschein eines Schutzes. Verschlüsselt sichern Sie von Hand.
• Aufbewahrung. Nach jeder geplanten Sicherung löscht heinzelhaus ältere vollständige Backups über der eingestellten Zahl endgültig, samt der inkrementellen Backups, die daran hängen. Die Zählung umfasst auch vollständige Backups, die Sie von Hand erstellt haben.
• Ausführung. Den Zeitplan führt der Hintergrunddienst (worker) in der Zeitzone der Installation aus. Er prüft jede Minute, ob die eingestellte Uhrzeit erreicht ist. Läuft er in dieser Minute nicht, entfällt die Sicherung an diesem Tag.
• Misslingt eine automatische Sicherung, gibt es die Benachrichtigung „Backup fehlgeschlagen“ in der Anwendung, aber keine E-Mail.

Wohin die Sicherungen kommen

Standardmäßig liegen sie im Ordner backups des Datenverzeichnisses, auf demselben Server wie die Daten. Das schützt vor einem Bedienfehler, nicht vor einem Plattenausfall oder Diebstahl. Bringen Sie die Sicherungen deshalb auf ein anderes Gerät, auf eine der zwei Arten.

Sicherungen herunterladen

1. Suchen Sie die Sicherung in der Karte „Vorhandene Sicherungen“. Der Download ist nur bei Status „Fertig“ möglich.
2. Klicken Sie in der Zeile auf das Download-Symbol. Es erscheint ein Menü mit „Datenbank-Dump“, „Dateien-Archiv“, „Anleitung“ und „Löschen“.
3. Laden Sie für eine vollständige Sicherung außer Haus alle drei Dateien herunter: „Datenbank-Dump“, „Dateien-Archiv“ und „Anleitung“. Die Dateien heißen zum Beispiel heinzelhaus-2026-10-08T03-00-00-voll-datenbank.dump. Bei verschlüsselten Sicherungen endet der Name auf .enc.
4. Speichern Sie die Dateien auf einer USB-Platte, einem NAS oder in einer anderen Ablage.

Einen anderen Speicherort einstellen

Damit neue Sicherungen automatisch auf einer anderen Platte oder einem NAS landen.

1. Binden Sie das Laufwerk zuerst in den Server ein. Es erscheint in der Oberfläche nur, was dem Container zur Verfügung steht. Wie das geht, steht unter Installation im Abschnitt „Eigene Anpassungen“. Das Laufwerk muss in den Diensten app und worker eingebunden sein, denn der Hintergrunddienst schreibt die geplanten Sicherungen.
2. Öffnen Sie die Karte „Speicherort“. Unter „Eingebundene Volumes“ stehen die Laufwerke, die der Anwendung zur Verfügung stehen, mit freiem Platz. Gekennzeichnet sind „nicht dauerhaft“ und „schreibgeschützt“. Klicken Sie ein Laufwerk an, oder tragen Sie unter „Zielverzeichnis“ einen absoluten Pfad ein, der mit / beginnt. Leer heißt: Standard /data/backups.
3. Klicken Sie auf „Ziel prüfen“. Die Antwort lautet „Ziel ist beschreibbar“, „Bitte beachten“ (mit Warnungen) oder „Ziel nicht nutzbar“.
4. Übernommen wird der Speicherort mit dem Knopf „Zeitplan speichern“ in der Karte „Zeitplan“. Die Karte „Speicherort“ hat keinen eigenen Speichern-Knopf.

Gut zu wissen

• „Bereits vorhandene Backups bleiben, wo sie sind, und weiterhin abrufbar.“ Nur neue Sicherungen gehen an den neuen Ort.
• Ein Ziel im Dateisystem des Containers selbst ist nicht dauerhaft. Backups dorthin gehen beim nächsten Update verloren.
• Bei knappem Platz warnt die Prüfung: „Der freie Speicherplatz reicht voraussichtlich nicht für ein weiteres Voll-Backup.“
• Der Hinweis in der Karte „Speicherort“ nennt zum Einbinden die Datei docker-compose.yml. Die verwaltet aber das Update und setzt sie zurück. Binden Sie das Laufwerk in der Datei docker-compose.override.yml ein.

Eine Sicherung löschen

1. Klicken Sie in der Zeile der Sicherung auf das Download-Symbol und wählen Sie „Löschen“.
2. Es fragt „Backup löschen?“ und erklärt: „Die Sicherung wird endgültig vom Server entfernt. Laden Sie sie vorher herunter, falls Sie sie behalten möchten.“
3. Klicken Sie auf „Endgültig löschen“. Es erscheint „Backup gelöscht.“

Ein vollständiges Backup, auf dem inkrementelle aufbauen, lässt sich nicht löschen: „Dieses Voll-Backup ist Basis für … inkrementelle Backup(s) und kann nicht gelöscht werden.“ Löschen Sie zuerst die inkrementellen.

Wiederherstellen

Eine Sicherung stellen Sie auf zwei Wegen zurück. Welcher passt, hängt davon ab, ob schon jemand in der Installation arbeitet.

Situation	Weg
Neuer, frisch installierter Server, noch kein Benutzer angelegt	In der Oberfläche: Ersteinrichtung → „Sicherung einspielen“
Laufende Installation, Rückkehr zu einem früheren Stand	Von Hand auf dem Server nach der Anleitung LIESMICH.txt

Auf einem neuen Server

Das ist der Weg für den Serverwechsel und für den Totalausfall. Er läuft in der Oberfläche der Ersteinrichtung und ist unter Erste Einrichtung im Abschnitt „Sicherung einspielen“ beschrieben. Nehmen Sie dafür eine vollständige Sicherung. Konten, Einstellungen und Daten kommen zurück, die Einrichtung entfällt.

Sicherungen aus CasaTastic, wie die Software vor Version 1.0 hieß, lassen sich einspielen. Das Dateiformat ist unverändert.

Von Hand auf dem laufenden Server

Damit Ihre IT eine Installation auf einen früheren Stand zurücksetzt.

Sie brauchen: root-Zugang zum Server, die Sicherung (Datenbank-Dump und Dateien-Archiv, bei Verschlüsselung vorher entschlüsselt) und den Projektordner. Die Befehle löschen den aktuellen Stand der Datenbank. Legen Sie vorher noch eine Sicherung des aktuellen Stands an, falls möglich.

1. Halten Sie Anwendung und Hintergrunddienst an. Beide halten Verbindungen zur Datenbank, sonst scheitert das Löschen:

   cd /opt/heinzelhaus     # Ihr Projektordner
   docker compose stop app worker

2. Spielen Sie die Datenbank zurück. Die Datei heißt datenbank.dump, beim Herunterladen heinzelhaus-…-datenbank.dump:

   docker compose exec -T db dropdb -U heinzelhaus --if-exists heinzelhaus
   docker compose exec -T db createdb -U heinzelhaus heinzelhaus
   cat datenbank.dump | docker compose exec -T db pg_restore -U heinzelhaus -d heinzelhaus --no-owner --no-privileges

   Die Optionen --no-owner und --no-privileges lassen die Rollen der Quelle außen vor. So lassen sich auch Sicherungen aus der Zeit vor Version 1.0 einspielen, deren Datenbank und Rolle noch casatastic hießen.

3. Spielen Sie die Dateien zurück. Bei einer inkrementellen Sicherung zuerst das zugehörige vollständige Backup, danach die inkrementellen in zeitlicher Reihenfolge, jeweils in dasselbe Verzeichnis. Das Datenverzeichnis liegt im Docker-Volume heinzelhaus_app-data (der Anfang des Namens ist Ihr HH_PROJEKT). Heißt Ihre Datei anders, etwa wie beim Herunterladen vergeben, passen Sie den Namen im Befehl an. Mit einem kurzen Hilfscontainer entpacken Sie das Archiv hinein und stellen die Rechte der Anwendung (Nummer 100, Gruppe 101) wieder her:

   docker run --rm -v heinzelhaus_app-data:/data -v "$PWD":/sicherung:ro alpine:3 \
     sh -c 'tar xzf /sicherung/dateien.tar.gz -C /data && chown -R 100:101 /data'

   Liegt das Datenverzeichnis nach Ihrer docker-compose.override.yml in einem Verzeichnis des Servers, entpacken Sie das Archiv mit tar xzf dateien.tar.gz -C /pfad/zum/datenverzeichnis dorthin.

4. Starten Sie alles wieder:

   docker compose up -d

   Das ist sicherer als nur docker compose start app worker: Es lässt die Einmal-Dienste init-daten (setzt die Rechte im Datenverzeichnis) und migrate (spielt Änderungen an der Datenbankstruktur ein, falls die Sicherung von einer älteren Version stammt) noch einmal laufen. Bei Betrieb mit Domain nennen Sie alle Compose-Dateien, siehe Installation.

5. Melden Sie sich an und prüfen Sie einige Kennzahlen. Der Datenbank-Dump ist in jeder Sicherung vollständig. Für die Datenbank genügt daher immer die zuletzt gesicherte Datei.

TODO

Vor Veröffentlichung klären: Der Schritt „Dateien zurückspielen“ mit einem Hilfscontainer ist hier abgeleitet. Die LIESMICH.txt nennt nur tar xzf dateien.tar.gz -C /pfad/zum/datenverzeichnis. Der Aufruf mit dem Volume heinzelhaus_app-data wurde auf einer Testinstallation nicht vollständig durchgespielt, nur der Entpackschritt in einem Wegwerf-Volume. Ebenso ist offen, ob die Wiederherstellung im laufenden Betrieb später einen eigenen Weg in den Einstellungen bekommt.

Eine verschlüsselte Sicherung ohne heinzelhaus entschlüsseln

Damit Sie an die Daten kommen, auch wenn keine Installation mehr läuft. Eine Verschlüsselung, die man nur mit der Anwendung wieder aufbekommt, wäre eine Falle.

Sie brauchen: einen beliebigen Rechner mit Node.js, das Skript backup-entschluesseln.mjs und das Passwort.

1. Legen Sie das Skript und die .enc-Dateien in einen Ordner.

2. Entschlüsseln Sie jede Datei, zum Beispiel:

   node backup-entschluesseln.mjs datenbank.dump.enc datenbank.dump

   Ebenso verfahren Sie mit dateien.tar.gz.enc und manifest.json.enc.

3. Das Skript fragt „Passwort der Sicherung:“. Die Eingabe wird nicht angezeigt. Danach meldet es „Entschlüsselt: …“.

4. Weiter geht es mit den Schritten der LIESMICH.txt, mit den Dateinamen ohne .enc.

Für Skripte können Sie das Passwort über die Umgebungsvariable HH_BACKUP_PASSWORT übergeben, nicht als Argument, denn Argumente stehen in der Prozessliste und in der Shell-Historie. Der alte Name CASATASTIC_BACKUP_PASSWORT wird weiter gelesen. Beim Einspielen über die Ersteinrichtung ist dieser Schritt nicht nötig, dort fragt heinzelhaus das Passwort selbst ab.

TODO

Vor Veröffentlichung klären: Das Skript backup-entschluesseln.mjs liegt im Projektordner unter scripts/. Quellcode erhalten nach dem README nur Lizenznehmer. Ob Kunden das Skript getrennt bekommen, etwa als Download auf dieser Seite, ist offen.

Fachdaten in eine andere Installation übertragen

Damit Sie Fachdaten (Objekte, Kontakte, Buchungen und alles Weitere) von einer heinzelhaus-Installation in eine andere übernehmen, ohne die Konten und Einstellungen der Zielinstallation zu überschreiben, zum Beispiel von einer Testinstallation in die Produktivinstallation.

Achtung

Verwenden Sie dafür nie ein einfaches pg_dump und pg_restore. Ein voller Dump nimmt Konten, Sitzungen, Passkeys, den zweiten Faktor und die Einstellungen mit. Beim Einspielen ersetzt er das Konto des Betreibers der Zielinstallation durch das der Quelle, der Betreiber ist ausgesperrt, und Mailzugang, Domain und Schnittstellenschlüssel sind überschrieben. Das Skript scripts/datenuebernahme.sh schließt diese Tabellen aus, im Skript selbst und nicht in einer Anleitung, die man beim Tippen vergisst.

1. Legen Sie in der Zielinstallation zuerst ein Backup an (Einstellungen → Reiter „Backup“).

2. Schreiben Sie auf der Quelle die Fachdaten in eine Datei, im Projektordner:

   ./scripts/datenuebernahme.sh export daten.dump

   Es meldet „Fachdaten nach daten.dump geschrieben.“ und „Nicht enthalten: …“.

3. Bringen Sie die Datei auf den Zielserver.

4. Spielen Sie sie dort ein:

   ./scripts/datenuebernahme.sh import daten.dump

   Das Skript warnt: „Diese Übernahme ersetzt die Fachdaten der Zielinstallation. Konten, Einstellungen und Briefköpfe bleiben unberührt.“ Es fragt „Vorher ein Backup angelegt? [ja/nein]“. Mit ja spielt es ein und meldet „Übernahme abgeschlossen.“

Nicht übertragen werden Benutzer samt Passwörtern, Sitzungen, Anmeldeverfahren, Passkeys, der zweite Faktor, offene Einladungen, die Einstellungen (Mail, Domain, Lexware, Update, Backup) und die Briefköpfe. Auch die Dateien aus dem Datenverzeichnis (Dokumente, Belege, Logos, Uploads) werden nicht übertragen, nur die Inhalte der Datenbank. Die Fachdaten der Zielinstallation werden ersetzt, nicht ergänzt.

So bleiben Ihre Daten sicher

• Aktivieren Sie den Zeitplan unter „Zeitplan“. Am besten täglich, mit einem vollständigen Backup pro Woche.
• Bringen Sie die Sicherungen regelmäßig auf ein anderes Gerät, entweder durch den Download oder durch einen eigenen Speicherort.
• Verschlüsseln Sie Sicherungen, die den Server verlassen, und bewahren Sie das Passwort getrennt auf.
• Bewahren Sie die .env getrennt vom Server auf.
• Prüfen Sie ab und zu auf dem Dashboard in der Kachel „Systemstatus“ (nur für Administratoren sichtbar), wann zuletzt gesichert wurde. Sie wird rot, wenn es noch kein Backup gibt oder das letzte mehr als sieben Tage zurückliegt. Die Vorabprüfung vor einem Update warnt bei sieben Tagen und mehr.
• Probieren Sie die Wiederherstellung einmal auf einem Testserver aus, bevor Sie sie im Ernstfall brauchen.

Häufige Fehler

Meldung	Ursache	Lösung
„Backup fehlgeschlagen“	Zum Beispiel zu wenig Platz oder kein Zugriff auf das Ziel. Der Grund steht daneben.	Prüfen Sie Platz und Speicherort.
„Das Passwort muss mindestens 12 Zeichen haben.“	Das Passwort der Sicherung ist zu kurz.	Wählen Sie ein längeres.
„Bitte bestätigen Sie den Hinweis zum Passwort.“	Das Häkchen fehlt.	Setzen Sie es.
„Der Pfad muss absolut sein, also mit „/“ beginnen.“	Das Zielverzeichnis ist relativ angegeben.	Tragen Sie einen absoluten Pfad ein.
„Ziel nicht nutzbar“	Das Verzeichnis existiert nicht oder ist schreibgeschützt.	Binden Sie das Laufwerk ein und prüfen Sie die Rechte.
„Diese Installation wird bereits benutzt. Eine Wiederherstellung ist hier nicht möglich.“	Das Einspielen über die Oberfläche geht nur ohne Benutzer.	Nutzen Sie den Weg „Von Hand auf dem laufenden Server“.
„Das Passwort ist falsch …“	Das Passwort der verschlüsselten Sicherung stimmt nicht.	Prüfen Sie es. Ohne das richtige Passwort ist die Sicherung verloren.
„Die Sicherung ist beschädigt oder wurde nachträglich verändert. Bitte spielen Sie eine andere Kopie ein.“	Die Datei ist unvollständig oder verändert.	Nehmen Sie eine andere Kopie.

Noch nicht möglich

• Wiederherstellen im laufenden Betrieb über die Oberfläche. Die Oberfläche spielt Sicherungen nur in der Ersteinrichtung ein.
• Ein externes Sicherungsziel, etwa Cloud oder SFTP. Sie stellen einen Speicherort auf einer eingebundenen Platte ein oder laden die Dateien herunter.
• Die ganze Sicherung als eine Datei herunterladen. Sie laden Datenbank-Dump, Dateien-Archiv und Anleitung einzeln. Für die Ersteinrichtung packen Sie sie zu einer .tar.gz-Datei zusammen.
• Automatisch verschlüsselte Sicherungen. Der Zeitplan sichert immer unverschlüsselt.
• Eine E-Mail bei fehlgeschlagener automatischer Sicherung. Es gibt nur die Benachrichtigung in der Anwendung.
• Die .env mitsichern. Sie liegt außerhalb des Datenverzeichnisses.

Weiter geht es hier

• Erste Einrichtung: Die Sicherung auf einem neuen Server einspielen.
• Updates: Vor jedem Update sichern.
• Installation: Eigene Laufwerke einbinden.