Umzug von CasaTastic auf heinzelhaus

Bis Version 0.6 hieß die Software CasaTastic. Ab Version 1.0 heißt sie heinzelhaus, und zwar auch hinter den Kulissen: Projektordner, Datenbank, Konfiguration und Speicherbereiche tragen jetzt den neuen Namen.

Wurde Ihre Installation vor 1.0 eingerichtet, zieht sie einmalig um. Dafür liefert der Hersteller ein Skript mit. Es kopiert Ihre Daten, benennt die Kopie um, zählt nach, ob nichts fehlt, und nimmt bei jedem Fehler alles zurück. Diese Seite erklärt, was sich ändert, was zu tun ist und was mit Ihren Daten geschieht.

Sie richtet sich an zwei Gruppen:

Sie sind …	Lesen Sie …
Verwalterin oder Verwalter	„Brauchen Sie diese Seite?“, „Das Wichtigste in Kürze“, „Was sich für Ihr Team ändert“, „Was mit Ihren Daten geschieht“, „Vorbereitung“ (Abschnitt „Für die Verwaltung“) und „Wenn etwas schiefgeht: der Rückweg“
IT-Dienstleister oder Betreuer des Servers	die ganze Seite, besonders „Vorbereitung“ (Abschnitt „Für den IT-Dienstleister“) und „Schritt für Schritt für den IT-Dienstleister“

Brauchen Sie diese Seite?

Ja, wenn Ihre Installation vor Version 1.0 eingerichtet wurde. Daran erkennen Sie es:

• In der Datei .env im Projektordner, der Konfigurationsdatei Ihrer Installation, fehlt der Eintrag HH_PROJEKT.
• Der Projektordner auf dem Server heißt in der Regel /opt/casatastic.
• Ein Update mit dem Update-Knopf (Seitenleiste → Verwaltung → „Einstellungen“ → Reiter „System“ → Karte „Software-Update“ → „Update jetzt installieren“) endet, sobald Version 1.0 erschienen ist, mit „Update fehlgeschlagen“ und der Meldung „Build fehlgeschlagen - Details im Protokoll“. Im „Update-Log“ derselben Karte steht dazu „HH_PROJEKT fehlt“.

Nein, wenn Sie heinzelhaus ab Version 1.0 neu installiert haben. Dort ist alles schon richtig. Dann hilft Ihnen die Seite Installation weiter.

Gut zu wissen

Bis zum Umzug läuft Ihre bisherige Fassung unverändert weiter. Die neue Version spielt sich nicht von allein ein: Das Ein-Klick-Update bricht ab, bevor ein laufender Teil von heinzelhaus angefasst wird. So entsteht nie ein halber Zustand. Neue Versionen erhalten Sie allerdings erst nach dem Umzug.

Achtung

Tragen Sie HH_PROJEKT nicht von Hand in die .env ein, um die Meldung „HH_PROJEKT fehlt“ loszuwerden, etwa als HH_PROJEKT=casatastic. Die neue Fassung sucht dann eine Datenbank und eine Rolle namens heinzelhaus, die in Ihrem Bestand noch casatastic heißen. Die Anwendung käme nicht an ihre Daten und würde nicht starten. Das Umzugsskript hielte die Installation außerdem für „bereits umgezogen“. Nutzen Sie den vorgesehenen Weg, den diese Seite beschreibt.

Das Wichtigste in Kürze

• Ihre Daten bleiben, wie sie sind. Datenbank und Dateien werden kopiert, nicht verändert. Das Skript zählt vorher und nachher nach. Stimmt etwas nicht, nimmt es alles zurück.
• Der Umzug ist einmalig. Ihr IT-Dienstleister oder die Person, die Ihren Server betreut, führt ihn durch. In heinzelhaus selbst ist dafür nichts einzustellen.
• Die Unterbrechung ist kurz. Die neue Fassung wird gebaut, während die alte weiterläuft. Nur zwischen Anhalten und Neustart ist heinzelhaus nicht erreichbar, bei einigen hundert Megabyte Daten wenige Minuten.
• Adresse und Konten bleiben. Ihr Team ruft heinzelhaus unter derselben Adresse auf und meldet sich mit denselben Konten an.
• Sie können zurück. Die alte Installation bleibt vollständig erhalten, bis jemand sie bewusst aufräumt.

Was sich für Ihr Team ändert

Das bleibt gleich

• Die Adresse, unter der Ihr Team heinzelhaus im Browser öffnet.
• Konten, Passwörter, Rollen und Rechte.
• Passkeys und Authenticator-Apps. Bestehende Passkeys bleiben gültig. In der Authenticator-App heißt der Eintrag weiter „CasaTastic“, und die Codes gelten weiter.
• Alle Daten: Objekte, Kontakte, Verträge, Buchungen, Dokumente, Briefköpfe und die Einstellungen, zum Beispiel für den E-Mail-Versand und den Zeitplan der Sicherungen.
• Vorhandene Sicherungen. Liegen sie im Standardordner des Datenverzeichnisses, werden sie mitkopiert.
• Ihr eigenes Erscheinungsbild. Haben Sie unter Einstellungen → Reiter „Erscheinungsbild“ ein eigenes Logo, einen eigenen Namen, einen Untertitel oder eine Primärfarbe gespeichert, gilt weiter Ihre Einstellung.
• Die Kennungen der Datenübernahme. Daran erkennt heinzelhaus Datensätze aus Karthago und PowerHaus wieder. Ein erneutes Einspielen aktualisiert also wie bisher, statt zu verdoppeln (siehe Erneut einspielen).

Das ändert sich

• Name und Aussehen. Wo bisher „CasaTastic“ stand, steht jetzt „heinzelhaus“, mit neuem Logo, neuen Farben und neuen Schriften. Nur ein Anzeigename, der noch auf „CasaTastic“ lautete, wird beim ersten Start der neuen Fassung entfernt. Dann gilt der Name „heinzelhaus“. Ein eigener Name bleibt.
• Neue Authenticator-Einträge. Wer die Authenticator-App neu einrichtet, sieht dort „heinzelhaus“.
• Namen von Sicherungsdateien. Neue Sicherungen heißen heinzelhaus-… statt casatastic-…. Ältere Sicherungen aus CasaTastic lassen sich weiter einspielen.
• DATEV-Export. Im Feld „Exportiert von“ steht künftig „heinzelhaus“.
• Browser-Einstellungen. Spaltenanordnung, Navigation und Toneinstellung merkt sich der Browser jedes Mitarbeiters. Sie werden beim ersten Aufruf automatisch übernommen. Niemand muss etwas neu einstellen.

Was mit Ihren Daten geschieht

Der Umzug kopiert, er verschiebt nichts. Das ist der Kern der Sicherheit.

• Das Original bleibt unberührt. Die alten Speicherbereiche werden beim Kopieren nur lesend geöffnet. Sie liegen nach dem Umzug unverändert auf dem Server, die alten Container sind nur angehalten.
• Die Kopie wird geprüft. Das Skript vergleicht für jeden Speicherbereich die Zahl der Einträge, die Summe der Dateigrößen und die Rechte.
• Die Zeilen werden gezählt. Vor dem Umzug und nach dem Neustart zählt das Skript die Zeilen von elf Tabellen: Objekte, Einheiten, Personen, Mietverträge, Sachkonten, Buchungen, offene Posten, Dokumente, Belege, Dateien der Akte und Benutzer. Weicht auch nur eine Zahl ab, bricht das Skript ab und nimmt den Umzug zurück.
• Der Inhalt bleibt, wie er ist. Buchungen, Belegnummern und Verträge werden nicht neu berechnet oder umgeschrieben. Beim ersten Start der neuen Fassung spielt heinzelhaus die Änderungen an der Datenbankstruktur ein, die seit Ihrer bisherigen Version dazugekommen sind. An Inhalten ändert die Umbenennung nur zwei Einträge in den Einstellungen: den Anzeigenamen „CasaTastic“, falls er noch so lautete, und die Repository-Adresse der Update-Quelle, falls dort genau die bisherige Standardadresse stand. Eigene Werte bleiben unberührt.
• Nicht kopiert werden die Import-Server. Die Speicherbereiche der Server für die Datenübernahme (SQL Server für Karthago, Firebird für PowerHaus) bleiben zurück, es sei denn, der IT-Dienstleister wählt die Option --mit-import-volumes. Die hochgeladene Sicherung selbst liegt im Datenverzeichnis und wird mitkopiert. Die Import-Server spielen sie beim nächsten Import neu ein.
• Kennwörter und Schlüssel bleiben. Alle bisherigen Einträge der .env werden übernommen, auch POSTGRES_PASSWORD und BETTER_AUTH_SECRET. Es werden Namen umgeschrieben und HH_PROJEKT, REPO_PFAD sowie die zwei Kennwörter für die Import-Server ergänzt.

Achtung

Die gesicherte alte Konfiguration .env.vor-heinzelhaus-<Zeitstempel> enthält Kennwörter. Der Zeitstempel hat die Form 20261008-143440. Bewahren Sie die Datei so sorgfältig auf wie die .env selbst und löschen Sie sie beim Aufräumen. In gebaute Programmteile gelangt sie nicht.

Ablauf im Überblick

1. Vorbereiten: Termin abstimmen, Team informieren, Sicherung anlegen und außer Haus bringen.
2. Neuen Stand holen: Der Projektordner auf dem Server bekommt den Stand 1.0.
3. Probelauf: Das Skript prüft alles und ändert nichts.
4. Umzug: Das Skript kopiert, benennt um und startet die neue Fassung.
5. Prüfen: Anmelden, Stichproben, eigene Skripte anpassen.
6. Aufräumen: Nach einigen Tagen die alte Installation entfernen.

Vorbereitung

Damit der Umzug reibungslos läuft und Sie jederzeit zurück können, erledigen Sie vorab Folgendes.

Für die Verwaltung

1. Legen Sie den Termin außerhalb der Arbeitszeit. heinzelhaus ist während des Umzugs wenige Minuten nicht erreichbar.
2. Informieren Sie Ihr Team. Angefangene Eingaben sollten vorher gespeichert sein.
3. Prüfen Sie, wann zuletzt gesichert wurde: Seitenleiste → „Dashboard“ → Kachel „Systemstatus“ (nur für Administratoren sichtbar) → Zeile „Letztes Backup“, zum Beispiel „Letztes Backup vor 3 Tagen“. Ist die Zeile rot, fehlt eine aktuelle Sicherung. Das ist der Fall, wenn es noch keine gibt („Es existiert noch kein Backup“) oder die letzte mehr als 7 Tage zurückliegt.
4. Notieren Sie sich einige Kennzahlen zum Vergleich, etwa die Zahl Ihrer Objekte (Seitenleiste → „Objekte“) und den Saldo eines Kontos (Seitenleiste → „Buchhaltung“ → Reiter „Sachkonten“, Konto anklicken).
5. Nach dem Umzug melden Sie sich an und vergleichen die notierten Werte. Stimmt etwas nicht, sagen Sie es sofort Ihrem IT-Dienstleister. Solange die alte Installation noch steht, lässt sich der Umzug zurücknehmen.

Für den IT-Dienstleister

1. Zugang: Sie brauchen root-Rechte auf dem Server. Bei einer Installation als Proxmox-Container arbeiten Sie im Container (auf dem Proxmox-Host pct enter <CTID>), nicht auf dem Host.
2. Sicherung außer Haus: Legen Sie ein vollständiges Backup an und laden Sie die Dateien herunter: Einstellungen → Reiter „Backup“ → Karte „Datensicherung“ → „Vollständiges Backup“, dann bei „Vorhandene Sicherungen“ das Download-Symbol → „Datenbank-Dump“ und „Dateien-Archiv“. Eine Sicherung, die nur auf demselben Server liegt, schützt nicht vor einem Plattenausfall. Mehr dazu unter Datensicherung und Wiederherstellung.
3. Schnappschuss, wenn möglich: Läuft heinzelhaus in einem Proxmox-Container oder in einer virtuellen Maschine, legen Sie vorher einen Schnappschuss an, sofern der Speicher das unterstützt. Das ist die einfachste Rückfallebene.
4. Platz im Docker-Speicher: Nötig ist die Größe aller zu kopierenden Daten plus 10 Prozent plus 1 GB Reserve. Zum Bauen kommen weitere 4 GB für Abbilder (die fertig gebauten Programmteile) und Zwischenspeicher dazu. Das Skript rechnet das selbst nach und bricht ab, wenn der Platz nicht reicht.
5. Internetzugang: Beim Bauen lädt Docker Basisabbilder und Pakete. Zusätzlich fragt das Skript an, ob die neue Repository-Adresse erreichbar ist.
6. Lauf einer Datenübernahme: Läuft gerade eine Übernahme aus Karthago oder PowerHaus, verwenden Sie später die Option --mit-import-volumes. Besser ist es, die Übernahme vorher abzuschließen.
7. Eigene Anpassungen sichten: Prüfen Sie Cron-Einträge, eigene Skripte, die Überwachung und die Datei docker-compose.override.yml (sie enthält örtliche Anpassungen wie Speichergrenzen oder Ablageorte) auf Verweise mit dem alten Namen. Das können zum Beispiel der Pfad /opt/casatastic, Containernamen wie casatastic-db-1, der Datenbankname casatastic oder Speicherbereiche mit dem Präfix casatastic_ sein. Diese Stellen müssen nach dem Umzug auf die neuen Namen zeigen.

Begriffe, kurz erklärt

heinzelhaus läuft auf dem Server in mehreren getrennten Containern: ein Container für die Anwendung, einer für die Datenbank und so weiter. Die Daten liegen in Volumes. Das sind Speicherbereiche von Docker, die ein Neubau der Container überdauern. Weitere Begriffe finden Sie unter Begriffe von A bis Z.

Schritt für Schritt für den IT-Dienstleister

Damit Ihre Installation auf die neuen Namen umgestellt wird, gehen Sie wie folgt vor. Voraussetzung ist der root-Zugang auf dem Server. Alle Befehle führen Sie als root im Projektordner aus.

1. Neuen Stand holen

Der Projektordner muss den Stand 1.0 enthalten, denn das Umzugsskript liegt erst dort. Der Weg von Hand ist der ruhigste:

cd /opt/casatastic
git fetch origin && git reset --hard origin/main

Die alte Repository-Adresse leitet auf die neue weiter. git reset --hard verwirft örtliche Änderungen an Dateien, die im Repository liegen (zum Beispiel eine von Hand geänderte docker-compose.yml). Die .env und die docker-compose.override.yml sind nicht im Repository und bleiben erhalten.

Alternativ holt auch der Update-Knopf den neuen Stand, bricht danach aber wie beschrieben mit „Build fehlgeschlagen“ ab. Das ist gewollt und richtet nichts an. Alle angemeldeten Mitarbeitenden sehen dabei allerdings die üblichen Update-Hinweise.

TODO

Vor Veröffentlichung klären: Wie kommt der Stand 1.0 in den Projektordner, wenn der Ordner kein Git-Repository ist oder der Zugang zum Repository fehlt (zum Beispiel bei einer Quellcode-Lieferung ohne Git-Verlauf)? Das Umzugsskript selbst kommt ohne Git aus, die Anleitung für diesen Fall fehlt noch.

2. Probelauf

bash scripts/umzug-heinzelhaus.sh --probe

Die Probe ändert nichts an Ihrer Installation. Sie zeigt:

• die Container und Speicherbereiche des alten Projekts,
• den Platzbedarf und den freien Platz,
• die Zeilenzahlen der Tabellen,
• die neuen Schlüssel der .env (ohne Werte),
• den neuen Projektordner,
• ob die neue Repository-Adresse erreichbar ist.

Findet sie ein Hindernis, endet sie mit einer Liste unter „Hindernisse:“ und dem Exit-Code 1. Beheben Sie diese Punkte und wiederholen Sie die Probe. Ohne Hindernisse endet sie mit „Keine Hindernisse gefunden.“ Mögliche Meldungen und ihre Ursachen stehen weiter unten unter „Häufige Meldungen“.

3. Umzug ausführen

bash scripts/umzug-heinzelhaus.sh 2>&1 | tee /root/umzug-heinzelhaus.log

Das Skript fragt einmal nach: „Umzug jetzt ausführen? Die Anwendung wird dabei kurz angehalten. [ja/nein]“. Tippen Sie ja. Bewahren Sie das Protokoll /root/umzug-heinzelhaus.log auf. Es hilft bei jeder Rückfrage an den Hersteller.

Das Bauen dauert einige Minuten, auf kleinen Maschinen bis etwa zehn. Währenddessen läuft die bisherige Fassung weiter. Erst danach ist heinzelhaus für wenige Minuten nicht erreichbar.

Am Ende meldet das Skript „Umzug abgeschlossen“ und nennt die Befehle zum späteren Aufräumen. Notieren Sie diese Befehle: Sie enthalten die genauen Namen Ihrer alten Container und Speicherbereiche.

4. Nach dem Umzug prüfen

1. Ausgabe des Skripts: Unter „Prüfen“ stehen drei Bestätigungen: „Dienste“, „Zeilen neu = alt“ und „Anwendung antwortet“.
2. Anmelden: Öffnen Sie die Adresse der Installation im Browser und melden Sie sich an, mit Passwort und Code oder per Passkey. Passkeys funktionieren weiter, weil PASSKEY_RP_ID in der .env unverändert bleibt.
3. Version: Einstellungen → Reiter „System“ → Karte „Version“. Dort muss bei „App-Version“ eine Version ab 1.0 stehen.
4. Update-Quelle: Karte „Update-Quelle“. Die „Repository-URL“ zeigt jetzt auf heinzelhaus, sofern vorher genau die Standardadresse eingetragen war. Mit „Nach Updates suchen“ in der Karte „Software-Update“ testen Sie die Verbindung. Eine frühere Fehlermeldung des Update-Knopfs räumt das Skript selbst weg.
5. E-Mail: Einstellungen → Reiter „E-Mail“ → „Test-E-Mail senden“.
6. PDF: Erzeugen Sie ein PDF, etwa ein Kontenblatt (Seitenleiste → „Buchhaltung“ → Reiter „Sachkonten“ → Konto anklicken → „PDF“).
7. Sicherung: Einstellungen → Reiter „Backup“. Die vorhandenen Sicherungen sind noch da. Legen Sie ein neues „Vollständiges Backup“ an.
8. Kennzahlen: Vergleichen Sie die Werte, die die Verwaltung vorher notiert hat.
9. Eigene Skripte: Stellen Sie Cron-Einträge, Überwachung und eigene Skripte auf die neuen Namen um (siehe Tabelle „Namen vorher und nachher“).

5. Später aufräumen

Warten Sie damit, bis die neue Fassung einige Tage einwandfrei läuft. Bis dahin sind die alten Container und Speicherbereiche Ihre Rückfallebene. Das Skript nennt am Ende die Befehle für Ihre Installation. Sie haben diese Form:

docker rm casatastic-db-1 casatastic-app-1 …
docker volume rm casatastic_db-data casatastic_app-data …
docker network rm casatastic_default
docker image rm casatastic-app casatastic-migrate …
rm /opt/heinzelhaus/.env.vor-heinzelhaus-<Zeitstempel>   # enthält Kennwörter
rm /opt/casatastic                                        # nur der Verweis

Stellen Sie vor rm /opt/casatastic alle Cron-Einträge und eigenen Skripte auf den neuen Pfad um. Das entfernt nur den Verweis, nicht den Projektordner.

Achtung

Die alten Speicherbereiche enthalten eine vollständige Kopie Ihrer Daten, auch der personenbezogenen. Mit docker volume rm sind sie endgültig weg. Führen Sie die Befehle nur aus, wenn Sie eine Sicherung außer Haus haben.

Was das Skript im Einzelnen tut

Das Skript arbeitet in dieser Reihenfolge. Die Anwendung ist nur von Schritt 2 bis Schritt 9 nicht erreichbar.

1. Bauen. Die neuen Programmteile entstehen, während die alte Fassung läuft. Scheitert der Bau, ist nichts verändert.
2. Anhalten. Zuerst werden die Anwendung und die übrigen Dienste angehalten, dann zählt das Skript die Zeilen der elf Tabellen, dann hält es die Datenbank an. Die alten Container werden gestoppt, nicht gelöscht.
3. Kopieren. Jeder Speicherbereich casatastic_<x> wird nach heinzelhaus_<x> kopiert. Das sind die Datenbank, das Datenverzeichnis und bei Betrieb mit Domain die Daten des vorgeschalteten Dienstes für HTTPS (Caddy). Das Original ist dabei nur lesend eingehängt. Die Kopie wird gegen das Original geprüft.
4. Umbenennen. In der Kopie werden Datenbankrolle und Datenbank in heinzelhaus umbenannt und das Kennwort aus der .env wird neu gesetzt. Die Rolle, mit der PostgreSQL eingerichtet wurde, lässt sich nicht umbenennen, solange man als sie angemeldet ist. Deshalb legt das Skript kurz eine Hilfsrolle an und löscht sie danach wieder.
5. .env anpassen. Neu sind HH_PROJEKT, REPO_PFAD und die beiden Kennwörter der Import-Server. Aus CASA_… wird HH_…. Ein vorhandenes COMPOSE_PROJECT_NAME wird auskommentiert. Die bisherige Datei bleibt als .env.vor-heinzelhaus-<Zeitstempel> daneben liegen.
6. Ordner umbenennen. /opt/casatastic wird zu /opt/heinzelhaus. Unter dem alten Pfad bleibt ein Verweis, damit Cron-Einträge und eigene Skripte weiter funktionieren.
7. Git-Adresse umstellen. origin zeigt danach auf …/heinzelhaus.git, aber nur, wenn die neue Adresse erreichbar ist. Ein eingebettetes Zugriffstoken bleibt erhalten und wird in der Ausgabe verdeckt.
8. Starten. Wie beim Update: docker-compose.prod.yml (Caddy) nur bei gesetzter DOMAIN, die docker-compose.override.yml zuletzt.
9. Prüfen. Alle Dienste laufen, die Einmal-Dienste migrate und init-daten sind sauber durchgelaufen, die Zeilenzahlen stimmen mit dem alten Stand überein und die Anwendung antwortet.

Wenn etwas schiefgeht: der Rückweg

Das Skript bricht ab

Bei jedem Fehler nimmt das Skript alles zurück, und zwar von selbst:

• Neue Container und die kopierten Speicherbereiche werden entfernt.
• .env, Projektordner und Git-Adresse kommen zurück.
• Die alten Container starten wieder, die Datenbank zuerst.

Am Ende steht: „Der Umzug ist fehlgeschlagen (Code …) und wurde zurückgenommen.“ Danach läuft die Installation wie vorher. Nur die gebauten Abbilder heinzelhaus-* bleiben liegen. Sie stören nicht.

Schlägt schon der Bau fehl, ist gar nichts verändert worden. Die alte Fassung ist dann nie angehalten worden.

Ein zweiter Aufruf nach einem erfolgreichen Umzug meldet „bereits umgezogen“ und ändert nichts.

Der Lauf wurde hart unterbrochen

Bei einem Stromausfall oder einem kill -9 kann das Skript nichts mehr zurücknehmen. Dann gehen Sie von Hand vor, wie im nächsten Abschnitt beschrieben. Die alten Speicherbereiche hat das Skript nur gelesen, Ihr Original ist also noch da.

Von Hand zurück zur alten Fassung

Diese Schritte brauchen Sie in zwei Fällen: nach einem hart unterbrochenen Lauf oder wenn der Umzug durchgelaufen ist und Sie in den ersten Tagen doch zurück möchten.

TODO

Vor Veröffentlichung klären: Das Skript beschreibt den Rückweg von Hand nur für den hart unterbrochenen Lauf. Die Schritte für den Rückweg nach einem erfolgreichen Umzug sind daraus abgeleitet und noch nicht auf einer Testinstallation durchgespielt.

1. Nur nach erfolgreichem Umzug: Legen Sie in heinzelhaus noch eine Sicherung an und laden Sie sie herunter (Einstellungen → Reiter „Backup“). Alles, was Ihr Team seit dem Umzug eingegeben hat, steht nur in der neuen Fassung. Die alten Speicherbereiche enthalten den Stand vom Umzugstag. Eingaben seit dem Umzug werden nicht automatisch in die alte Fassung übertragen.

2. Neue Container anhalten:

   docker stop $(docker ps -q --filter "label=com.docker.compose.project=heinzelhaus")

   Nach einem hart unterbrochenen Lauf entfernen Sie hier stattdessen Container und Speicherbereiche des neuen Projekts. Sehen Sie sich diese vorher an:

   docker ps -a --filter "label=com.docker.compose.project=heinzelhaus"
   docker volume ls --filter "label=com.docker.compose.project=heinzelhaus"

   Danach entfernen Sie sie mit docker rm -f, docker volume rm und docker network rm.

3. .env zurückholen:

   cp /opt/heinzelhaus/.env.vor-heinzelhaus-<Zeitstempel> /opt/heinzelhaus/.env

   Liegt der Projektordner noch unter dem alten Namen, nehmen Sie den Pfad /opt/casatastic.

4. Ordner zurückbenennen, falls er schon umbenannt wurde: rm /opt/casatastic entfernt nur den Verweis, danach mv /opt/heinzelhaus /opt/casatastic. Nach einem erfolgreichen Umzug können Sie diesen Schritt auch weglassen. Der alte Pfad führt dann über den Verweis in den Ordner.

5. Alte Container starten, die Datenbank zuerst. Die Namen zeigt docker ps -a --filter "label=com.docker.compose.project=casatastic". Starten Sie casatastic-db-1, warten Sie einen Moment und starten Sie dann die übrigen, die vorher liefen: Anwendung, Hintergrunddienst, PDF-Dienst und Updater (bei Betrieb mit Domain auch Caddy). Die Einmal-Dienste migrate und init-daten brauchen Sie nicht.

   docker start casatastic-db-1
   docker start casatastic-app-1 casatastic-worker-1 casatastic-pdf-1 casatastic-updater-1

6. Prüfen: Melden Sie sich an und kontrollieren Sie unter Einstellungen → Reiter „System“ → Karte „Version“, dass wieder die alte Fassung läuft.

Gut zu wissen

Mit der zurückgeholten .env bricht jeder Compose-Befehl im Projektordner wieder mit „HH_PROJEKT fehlt“ ab. Das ist gewollt. Es schützt davor, versehentlich eine zweite, leere Installation neben der alten zu starten. Wollen Sie später erneut umziehen, entfernen Sie vorher die Container, Speicherbereiche und das Netz des Projekts heinzelhaus. Sonst meldet die Probe Hindernisse.

Achtung

Entfernen Sie nur Container und Speicherbereiche des Projekts heinzelhaus, niemals die des Projekts casatastic. Die alten sind Ihr unverändertes Original.

Namen vorher und nachher

Was	bis 0.6	ab 1.0
Name der Docker-Installation (Compose-Projekt), bestimmt die Namen von Containern und Speicherbereichen	casatastic, fest in der docker-compose.yml	HH_PROJEKT in der .env, Vorgabe heinzelhaus
Speicherbereiche (Volumes)	casatastic_db-data, casatastic_app-data …	heinzelhaus_db-data, heinzelhaus_app-data …
Container	casatastic-app-1, casatastic-db-1 …	heinzelhaus-app-1, heinzelhaus-db-1 …
Datenbank und Datenbankrolle	casatastic	heinzelhaus
Projektordner	/opt/casatastic	/opt/heinzelhaus, am alten Pfad bleibt ein Verweis
Umgebungsvariablen (in der .env und beim Aufruf von install.sh)	CASA_2FA_PFLICHT, CASA_ZUGANG, CASA_IP, CASA_DOMAIN, CASATASTIC_BACKUP_PASSWORT	HH_2FA_PFLICHT, HH_ZUGANG, HH_IP, HH_DOMAIN, HH_BACKUP_PASSWORT
Variablen von scripts/proxmox-install.sh	CASA_TOKEN, CASA_CTID, CASA_HOSTNAME …	HH_TOKEN, HH_CTID, HH_HOSTNAME …
Kennwörter der Import-Server	fester Vorgabewert	zufällig, in der .env (MSSQL_SA_PASSWORD, FIREBIRD_PASSWORD)
Repository	https://git.it-flores.de/l.flores/casatastic	https://git.it-flores.de/l.flores/heinzelhaus, die alte Adresse leitet weiter
Anzeigename in Authenticator-App und Passkey-Dialog	„CasaTastic“	„heinzelhaus“, bestehende Einträge bleiben gültig
Benutzerkennung der Anwendung im Container	100 / 101	unverändert 100 / 101, die Dateirechte im Datenverzeichnis bleiben

Die alten Variablennamen werden weiter gelesen, wenn der neue Name fehlt. Das Umzugsskript schreibt die .env trotzdem auf die neuen Namen um.

Optionen des Skripts

Option	Wirkung
--probe	Nur prüfen und berichten, nichts verändern.
--alt-projekt NAME	Name des alten Projekts. Vorgabe: COMPOSE_PROJECT_NAME aus der .env, sonst casatastic. docker ps -a zeigt die vorhandenen Namen.
--neu-projekt NAME	Name des neuen Projekts. Vorgabe: der alte Name, in dem casatastic durch heinzelhaus ersetzt ist (aus casatastic-demo wird heinzelhaus-demo).
--mit-import-volumes	Kopiert auch die Speicherbereiche der Import-Server (mssql-data, firebird-data). Nur nötig, wenn gerade eine Datenübernahme läuft.
--ohne-verzeichnis	Den Projektordner nicht umbenennen. REPO_PFAD zeigt dann auf den bisherigen Ordner.
--ziel-verzeichnis PFAD	Anderer neuer Ordner. Vorgabe: im Ordnernamen casatastic durch heinzelhaus ersetzt.
--ohne-bau	Nicht bauen. Die Abbilder <neues Projekt>-<dienst> müssen schon vorliegen. Für Server, die zum Bauen zu wenig Speicher haben.
--ja	Ohne Rückfrage. Ohne Terminal ist --ja Pflicht.

Sonderfälle

• Datenbank in einem Verzeichnis des Servers. Hat die docker-compose.override.yml den Speicherbereich der Datenbank durch ein Verzeichnis des Servers ersetzt, bricht das Skript ab: „Die Datenbank liegt nicht in einem Docker-Volume …“. Die Umbenennung geschähe sonst am Original. Der Umzug geht dann nur von Hand: in der Oberfläche sichern, das Verzeichnis kopieren, in der Override-Datei auf die Kopie zeigen und Rolle und Datenbank wie in Schritt 4 der Liste „Was das Skript im Einzelnen tut“ umbenennen. Sprechen Sie vorher mit dem Hersteller (info@it-flores.de).
• Anderer Projektname. Lief die alte Installation unter einem anderen Namen, liest das Skript ihn aus COMPOSE_PROJECT_NAME in der .env. Sonst geben Sie ihn mit --alt-projekt an.
• Kennwort des SQL-Servers für den Import. SQL Server übernimmt sein Kennwort nur beim ersten Start auf einem leeren Speicherbereich. Mit --mit-import-volumes schreibt das Skript deshalb den bisherigen festen Wert in die .env, sonst einen zufälligen.
• Alter Updater. Er steckt im alten Abbild und ist nach dem Umzug nur angehalten. Der neue Updater räumt beim Update nur Container seines eigenen Projekts auf. Die angehaltenen alten bleiben bis zum Aufräumen stehen.
• Betrieb mit Domain. Das Skript erkennt am Eintrag DOMAIN in der .env selbst, dass Caddy mitläuft, und startet die Dienste entsprechend. Die Adresse und der Eintrag PASSKEY_RP_ID bleiben unverändert.

TODO

Vor Veröffentlichung klären: Für den Fall „Datenbank in einem Verzeichnis des Servers“ gibt es nur die Grobschritte der Herstelleranleitung. Eine genaue Anleitung mit Befehlen fehlt.

Häufige Meldungen

Meldung	Bedeutung und Abhilfe
„HH_PROJEKT fehlt in .env - vor 1.0 eingerichtete Installation? Einmalig scripts/umzug-heinzelhaus.sh ausfuehren“	Die gewollte Sperre. Führen Sie den Umzug aus.
„Bitte als root ausführen (oder mit sudo).“	Das Skript braucht root-Rechte.
„Die docker-compose.yml in … ist noch die alte Fassung.“	Der Stand 1.0 fehlt im Projektordner. Holen Sie ihn zuerst (Schritt 1).
„Keine Container des Projekts … gefunden.“	Die alte Installation läuft unter anderem Namen. Geben Sie ihn mit --alt-projekt an.
„Zu wenig Platz: … MB nötig, … MB frei.“	Schaffen Sie Platz im Docker-Speicher oder erweitern Sie die Platte.
„Zielvolume heinzelhaus_… existiert bereits (Rest eines früheren Laufs?)“	Prüfen Sie zuerst, was in dem Volume liegt und ob dort schon eine andere heinzelhaus-Installation läuft. Nur wenn es ein Rest ist, entfernen Sie es mit docker volume rm.
„Es gibt bereits Container des Projekts heinzelhaus“	Entweder hat ein früherer Lauf Reste hinterlassen, oder dort läuft schon eine andere Installation. Prüfen Sie das, bevor Sie etwas entfernen.
„Ohne Terminal nur mit –ja.“	Das Skript läuft ohne Tastatur, etwa aus einem Auftrag. Rufen Sie es mit --ja auf.
„Bau fehlgeschlagen — es wurde nichts verändert.“	Meist fehlt Internetzugang, Platz oder Arbeitsspeicher. Die alte Fassung läuft weiter.
„Zeilenzahlen weichen ab: …“	Die Prüfung nach dem Start hat einen Unterschied gefunden. Das Skript nimmt alles zurück. Wiederholen Sie den Lauf nicht blind, sondern schicken Sie das Protokoll an den Hersteller.
„Diese Installation ist bereits umgezogen“	Nichts zu tun. Das Skript ändert bei einem zweiten Aufruf nichts.

Alternative: neuer Server mit Sicherung

Gut zu wissen

Ziehen Sie ohnehin auf einen neuen Server um, können Sie dort heinzelhaus ab 1.0 frisch installieren und eine Sicherung einspielen, statt dieses Skript zu verwenden. Sicherungen aus CasaTastic lassen sich in heinzelhaus einspielen, das Dateiformat ist unverändert. Das Einspielen geht nur in der Ersteinrichtung einer frischen Installation. Verwenden Sie dafür ein vollständiges Backup. Die Schritte stehen unter Datensicherung und Wiederherstellung und Erste Einrichtung.

Die .env gehört nicht zur Sicherung. Übernehmen Sie den Eintrag BETTER_AUTH_SECRET aus der alten .env in die neue, bevor Sie die Sicherung einspielen. Sonst funktionieren eingerichtete Authenticator-Apps auf dem neuen Server nicht mehr.

Wie es weitergeht

• Neue Versionen installieren Sie nach dem Umzug wie gewohnt per Knopfdruck: Updates.
• Rollen, Rechte und die Pflicht zur starken Anmeldung bleiben unverändert: Anmeldesicherheit und Zwei-Faktor-Pflicht.
• Name und Aussehen Ihrer Installation: Erscheinungsbild.
• Eine Übernahme aus Karthago oder PowerHaus nach dem Umzug: Überblick und Ablauf.