Updates

Neue Versionen von heinzelhaus installieren Sie mit einem Klick in den Einstellungen. Der Updater-Dienst auf dem Server holt den neuen Programmstand, baut die Container neu, spielt Änderungen an der Datenbankstruktur ein und startet alles wieder. Ihre Daten bleiben dabei unberührt.

Damit Ihre Installation auf dem neuesten Stand ist, mit Fehlerbehebungen und Anpassungen an Gesetzesänderungen.

Sie brauchen: die Rolle „Administrator“ mit starker Anmeldung (siehe Anmeldesicherheit und Zwei-Faktor-Pflicht). Der Updater-Dienst muss auf dem Server laufen.

Neue Versionen gehören zum optionalen Wartungspaket. Ohne Wartungsvertrag bleibt der zuletzt installierte Stand dauerhaft nutzbar, erhält aber keine Updates mehr, siehe Häufige Fragen.

Installationen aus der Zeit vor Version 1.0 bekommen erst nach dem einmaligen Umzug von CasaTastic auf heinzelhaus wieder Updates.

Vor dem Update

Sicherung anlegen

Legen Sie vor jedem Update ein Backup an, siehe Datensicherung und Wiederherstellung. Die Vorabprüfung erinnert daran.

Die Vorabprüfung lesen

Unter Seitenleiste → Verwaltung → „Einstellungen“ → Reiter „System“ → Karte „Software-Update“ steht die „Vorabprüfung“. Jeder Punkt hat den Stand „In Ordnung“, „Warnung“ oder „Fehler“. Mit „Erneut prüfen“ prüfen Sie nach einer Änderung noch einmal.

Punkt	Was er prüft	Wann Warnung oder Fehler
„Verwaltete Dateien“	Ob Programmdateien auf dem Server von Hand geändert wurden	Warnung: Das Update setzt diese Dateien auf den ausgelieferten Stand zurück und legt die Änderungen vorher als Patch unter /data/update ab. Auch eine Warnung, wenn der Updater noch keinen Lagebericht abgelegt hat: „Läuft er? Auf dem Server: docker compose up -d updater.“
„Freier Speicherplatz“	Ob für den Neubau genug Platz ist	Fehler unter 2 GB frei, das Update ist gesperrt. Warnung unter 5 GB.
„Datensicherung“	Wann zuletzt gesichert wurde	Warnung, wenn es keine abgeschlossene Sicherung gibt oder die letzte sieben Tage oder älter ist
„Datenbank-Migrationen“	Ob noch Änderungen an der Datenbankstruktur ausstehen	Warnung bei ausstehenden. Das Update spielt sie automatisch ein.
„Konfiguration (.env)“	Ob in der .env alle Pflichteinträge stehen	Fehler, wenn welche fehlen: Ohne sie starten die Container nach dem Update nicht mehr.

Bei einem Fehler ist „Update jetzt installieren“ gesperrt. Darunter steht dann: „Das Update ist gesperrt: … Bitte den oben genannten Punkt beheben und erneut prüfen.“ Bei Platzmangel schaffen Sie Platz, zum Beispiel durch alte Datensicherungen oder hochgeladene Karthago-Dateien, die Sie nicht mehr brauchen.

Nach einer neuen Version suchen

Klicken Sie auf „Nach Updates suchen“. Das Ergebnis lautet „Aktuell“ oder „Neuer Stand verfügbar“, jeweils mit der Kurzbeschreibung der letzten Änderung und ihrem Datum.

Außerdem prüft der Hintergrunddienst einmal täglich, ob eine neue veröffentlichte Version vorliegt. Er vergleicht Versionsmarken, nicht einzelne Zwischenstände. Ist eine neue da, erhalten Sie einmal die Benachrichtigung „Version … verfügbar“ mit einem Link zu Einstellungen → „System“. Für jede Version gibt es höchstens eine Meldung. Erreicht der Server die Update-Quelle nicht, etwa ohne Internetzugang, bleibt die Prüfung ohne Meldung und wird erst am nächsten Tag wiederholt.

Das Update installieren

Damit der neue Stand läuft. Die Anwendung ist dabei einige Minuten nicht erreichbar. Planen Sie das Update außerhalb der Arbeitszeit.

1. Prüfen Sie die Vorabprüfung und legen Sie ein Backup an.
2. Klicken Sie auf „Update jetzt installieren“.
3. Es fragt „Update jetzt installieren?“ und erklärt: heinzelhaus lädt den neuesten Stand aus der Update-Quelle, baut die Anwendung neu und startet sie. Das dauert einige Minuten, in dieser Zeit ist die Anwendung nicht erreichbar, und alle Benutzer werden benachrichtigt. Klicken Sie auf „Update starten“.
4. Es erscheint „Update angestoßen — der Updater-Dienst übernimmt jetzt.“ Alle Benutzer erhalten die Benachrichtigung „Update gestartet“.
5. Warten Sie. Als Administrator sehen Sie die Schritte „Vorwarnzeit läuft“, „Neuen Stand von GitHub holen“, „Container neu bauen“, „Datenbank aktualisieren“ und „Dienste neu starten“ mit Fortschrittsanzeige und Protokoll. Der Schritt heißt „von GitHub“, auch wenn Ihre Quelle ein anderes Repository ist.
6. Am Ende erscheint „Update abgeschlossen“, und die Seite lädt sich neu. Oder es erscheint „Update fehlgeschlagen“ mit dem Grund. Die bisherige Fassung läuft dann unverändert weiter.

Im Reiter „System“ stehen danach in der Karte „Version“ die „App-Version“, der „Git-Stand“ und „Letztes Update“. Das „Update-Log“ in der Karte „Software-Update“ zeigt das Protokoll.

Was Ihr Team sieht

• 60 Sekunden vor dem Start erscheint bei allen Angemeldeten oben rechts „Update in Kürze“ mit einem Countdown und der Bitte: „Bitte schließen Sie angefangene Eingaben jetzt ab“. Sie können in dieser Zeit weiterarbeiten.
• Während des Updates sehen Administratoren „Update läuft“ mit den Schritten. Alle anderen sehen die Seite „Wartungsarbeiten“: „heinzelhaus wird gerade aktualisiert und ist für einige Minuten nicht bedienbar. Diese Seite öffnet sich von selbst wieder, sobald es weitergeht — Sie müssen nichts tun.“ Angefangene Eingaben, die noch nicht gespeichert wurden, gehen dabei verloren.
• Danach lädt sich die Seite von selbst neu.

Was auf dem Server passiert

Der Updater-Dienst arbeitet in dieser Reihenfolge:

1. Er holt den neuen Stand aus dem Git-Repository des Projektordners (git fetch). Änderungen an Programmdateien, die jemand von Hand vorgenommen hat, sichert er als verworfen-<Zeitstempel>.patch unter /data/update und setzt den Ordner auf den ausgelieferten Stand zurück. Die Dateien .env und docker-compose.override.yml bleiben unberührt.
2. Er baut alle Container neu. Auf kleinen Maschinen dauert das bis zu etwa zehn Minuten.
3. Er prüft vorab, ob alle eingebundenen Dateien existieren. Fehlt eine, bricht er ab, bevor Dienste berührt wurden, und die bisherige Fassung läuft unverändert weiter.
4. Er startet die Dienste neu. Der Dienst migrate spielt Änderungen an der Datenbankstruktur ein. Bleiben Dienste liegen, versucht er es bis zu dreimal. Gelingt es nicht, meldet er: „Dienste konnten nicht gestartet werden (…). Vermutlich zu wenig Arbeitsspeicher - auf dem Server ‘docker compose up -d’ ausfuehren.“
5. Er räumt auf: alte namenlose Abbilder, den Bau-Zwischenspeicher (vollständig, wenn weniger als 10 GB frei sind) und beendete Einmal-Container. Er entfernt nie Volumes, Daten oder hochgeladene Sicherungen.
6. Zuletzt erneuert er sich selbst.

Bei Betrieb mit Domain bindet der Updater die Datei docker-compose.prod.yml (Caddy) ein, sobald DOMAIN in der .env steht.

Die Karten im Reiter „System“

Karte	Inhalt
„Version“	„App-Version“, „Git-Stand“ und „Letztes Update“
„Update-Quelle“	„Repository-URL“, „Branch“ und „Zugriffstoken (optional)“ mit „Speichern“. Für private Repositories ein Token mit Lesezugriff. GitHub und Gitea werden unterstützt.
„Software-Update“	Vorabprüfung, „Nach Updates suchen“, „Update jetzt installieren“ und „Update-Log“
„Versionsverlauf“	Was sich in jeder Version geändert hat
„Über heinzelhaus“	Version, Hersteller, Webadresse und die Pflichtzeile des Herstellers

Achtung

Die Einstellungen der Karte „Update-Quelle“ wirken nur auf „Nach Updates suchen“ und auf die Meldung über neue Versionen. Das Update selbst holt immer vom Git-Remote origin im Projektordner und von dessen aktuellem Zweig. Das Zugriffstoken dafür steht in der Git-Adresse in .git/config. Ändern Sie die Quelle des Updates, ändern Sie dort die Adresse mit git remote set-url origin ….

Von der Kommandozeile aktualisieren

Der Updater-Dienst ist der übliche Weg. Auf dem Server geht es auch von Hand, im Projektordner:

./update.sh

Das Skript holt den neuen Stand mit git pull --ff-only und baut und startet die Container neu. Es wählt dieselben Compose-Dateien wie der Updater: docker-compose.prod.yml nur bei gesetzter DOMAIN, die Datei docker-compose.override.yml zuletzt. Fehlt in der .env der Eintrag HH_PROJEKT, bricht es mit einem Hinweis auf den Umzug ab.

Eigene Anpassungen und Updates

Das Update setzt die Programmdateien auf den ausgelieferten Stand zurück: docker-compose.yml, docker-compose.prod.yml, Dockerfile und Caddyfile. Dauerhafte Anpassungen gehören in die .env oder in docker-compose.override.yml. Nur diese beiden bleiben bei Updates unangetastet. Wie, steht unter Installation.

Häufige Meldungen

Meldung	Ursache	Lösung
„Das Update ist gesperrt: …“	Ein Punkt der Vorabprüfung steht auf „Fehler“.	Beheben Sie den Punkt und klicken Sie auf „Erneut prüfen“.
„Die Anwendung darf nicht in … schreiben. Der Updater-Dienst legt dieses Verzeichnis an; bitte ihn einmal neu starten (docker compose up -d updater).“	Das Verzeichnis für den Update-Status hat falsche Rechte.	Starten Sie den Updater-Dienst auf dem Server neu.
Es passiert nach dem Klick nichts, der Status bleibt stehen	Der Updater-Dienst läuft nicht.	Starten Sie ihn mit docker compose up -d updater. docker compose logs updater zeigt, was er meldet.
„Update fehlgeschlagen“, im Log „HH_PROJEKT fehlt“	Die Installation stammt aus der Zeit vor Version 1.0.	Siehe Umzug von CasaTastic auf heinzelhaus.
„git fetch fehlgeschlagen - Details im Protokoll“	Das Repository ist nicht erreichbar, oder das Zugriffstoken stimmt nicht.	Prüfen Sie Internetzugang und Token in der Git-Adresse.
„Build fehlgeschlagen - Details im Protokoll“	Meist fehlt Internetzugang, Platz oder Arbeitsspeicher.	Prüfen Sie das „Update-Log“. Die bisherige Fassung läuft weiter.
„Dienste konnten nicht gestartet werden (…)“	Vermutlich zu wenig Arbeitsspeicher.	Führen Sie auf dem Server docker compose up -d aus (bei Betrieb mit Domain mit allen Compose-Dateien, siehe Installation).

Noch nicht möglich

• Zurück auf eine ältere Version. In der Oberfläche gibt es keinen Weg zurück. Haben Sie vor dem Update gesichert, kommen Sie mit der Sicherung zum früheren Datenstand zurück, siehe Datensicherung und Wiederherstellung.
• Eine Quelle für das Update in den Einstellungen wählen. Das Update folgt dem Git-Remote origin des Projektordners.

Weiter geht es hier

• Datensicherung und Wiederherstellung: Vor dem Update sichern.
• Installation: Eigene Anpassungen, die ein Update überstehen.
• Umzug von CasaTastic auf heinzelhaus: Für Installationen vor 1.0.