Zum Inhalt

Migration auf die charly-VM

Diese Anleitung beschreibt den Prozess der Migration auf die charly-VM für das charly-System unter macOS. Sie umfasst die Sicherung der Daten vom alten Server, die Installation charly-VM auf dem neuen Server und das Einspielen der Sicherung in die charly VM.

Diagram Migration auf die charly-VM

Voraussetzungen

  • Ausreichend Speicherplatz auf dem Quellserver
  • Administrator-Zugriff auf den Server
  • Terminal mit Zsh

WICHTIG

Die Installation der charly-VM ist auf Macs mit Intel-Prozessor nicht möglich. Führen Sie die Migration ausschließlich dann durch, wenn die charly-VM auf einem Mac mit ARM-Prozessor (z. B. M1, M2) installiert wird.

WICHTIG

Der Benutzer muss Administrator auf dem macOS sein und der Benutzer im Terminal muss der Nutzer sein, der auch unter macOS angemeldet ist.

Verlauf der Migration

Die Migration auf die charly-VM verläuft in wenigen Schritten, die teilweise auch parallel durchgeführt werden können.

klassische Installion charly-VM
Backup erstellen Installation der charly-VM ohne Daten
Freigeben des Backup-Ordners als SMB Share. Schon mögliche bevor das Backup fertig gestellt ist. Die VM mit dem SMB-Share konfigurieren. Schon mögliche bevor das Backup fertig gestellt ist.
Backup wiederherstellen
Installation deaktivieren

Das charly-Server-Skript

Das charly-Server Skript muss auf dem alten und dem neuen Server installiert werden.

Zuerst muss der macOS Paketmanager brew installiert werden.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

WICHTIG

Am Ende fordert die brew Installation auf, noch einige Dinge als "Next steps" in der Kommandozeile einzugeben. Führen Sie die 3 Kommandos nacheinander aus.

Prüfen, ob homebrew schon installiert ist: 

brew --version

Hier sollte eine Versionnummer ausgegeben werden.

Dann kann das charly-server Skript mit folgendem Befehl installiert werden: 

/bin/zsh -c "$(curl -fsSL https://charly-cdn-solutio.s3.amazonaws.com/release/macos/charly-server-install.zsh)"

Prüfen, ob charly-server installiert wurde: 

charly-server -help

Export der klassischen Installation

Hier gibt es 2 Möglichkeiten. Entweder es wird am Vortag ein tägliches Backup konfiguriert, dass dann in der charly-VM restauriert wird.

Oder es wird ein manuelles Backup erstellt.

Tägliches Backup konfigureren

charly-server export backup-config

Normaler Export mit allen Daten

charly-server export normal -skip_iso true -backup_variant advanced

Es sollte dabei die empfohlene, inkrementelle Backup-Variante (-backup_variant advanced) verwendet werden. Nur damit kann dann der restore in der VM ausgeführt werden. Wenn ein klassisches Backup erzeugt wird (-backup_variant simple), dann muss eine ISO erzeugt werden (-skip_iso false) und mit der export.iso installiert werden!

-skip_iso true bedeutet hier, dass keine ISO-Datei erstellt wird, da später aus dem SMB-Share restauriert wird und diese nicht benötigt wird.

Wird keine ISO-Datei erstellt, muss der Export Ordner unter macOS als SMB-Share freigegeben werden. Siehe den Pfad export_path bei der Ausführung des charly-server export normal Befehls.

Schneller Export mit "databasiso"

Es kann auch ein Mittelweg gegangen werden, d.h. es kann eine ISO für die Installation erstellt werden, die nur das Database Backup und die Konfiguration enthält und deshalb schneller geht. Das bietet sich an, wenn noch kein Export vorliegt und der Export aufgrund der Datenmenge sehr lange dauern würde.

Damit kann dann eine charly-VM installiert werden, die schon voll funktionsfähig ist und wo nur die Ablage Daten fehlen.

charly-server export databaseiso -backup_variant advanced

Direkt danach kann die Installation mit der export.iso gestartet werden und gleichzeitig kann der normale export starten:

charly-server export normal -skip_iso true -backup_variant advanced

Installation der charly-VM

Auch hier gibt es prinzipiell 2 Möglichkeiten

  1. Installation ohne ISO. Das ist der empfohlene Weg. Die Daten werden später aus dem SMB-Share Backup eingelesen.
  2. Installation mit ISO. Bei Erstellen des Backups kann auch eine ISO erzeugt werden. Diese kann bei der Installation direkt verwendet werden. Dann muss aber mit der Installation gewartet werden, bis das Backup fertig ist.

Während der Installation kann man die ISO-Datei angeben. Wenn ein klassisches Backup erzeugt wurde, dann muss mit der export.iso installiert werden!

Die Installation startet durch folgendes Kommando: 

charly-server install

Wenn man erneut installieren möchte, muss die aktuelle Installation gestoppt werden: 

charly-server vm stop

Für mehr Informationen folgen Sie der Anleitung.

VM Backup konfigurieren und Backup einspielen

Das Export-Verzeichnis muss unter macOS frei gegeben werden. In den "Systemeinstellungen - Allgemein - Teilen" die Dateifregabe aktivieren, das Export-Verzeichnis in die Liste aufnehmen und unter "Optionen" die SMB Dateifreigabe aktivieren und den Benutzer für die Dateifreigabe aktivieren

In der charly-VM muss das auf macOS freigegebene SMB Share eingerichtet werden. In dieses wird die charly-VM dann täglich ein Backup sichern. Wenn mit einer ISO installiert wurde, dann entfällt dieser Schritt.

charly-server vm backup-config

Es muss hier das inkrementelle Backup gewählt werden. Wenn ein klassisches Backup erzeugt wurde, dann muss mit der export.iso installiert werden!

WICHTIG

Wenn beide Installation ein backup-config durchgeführt haben, erstellen beide ein nächtliches Backup in den Export-Ordner. Deshalb sollte das backup-config der charly-VM erst kurz vor dem Restore der Daten passieren und das Alt-System sollte danach deaktivert werden.

Wenn das Backup des Alt-Systems verfürgbar ist, kann es eingespielt werden.

charly-server vm restore

Für mehr Informationen folgen Sie der Anleitung.

Alt-System deaktivieren

Wenn die Installation der charly-VM und das Einspielen der Daten erfolgreich war, muss das Alt-System deaktiviert werden.

charly-server export deactivate

Weitere Hinweise

Die Datenbank auf Toast und LOB Fehler prüfen

Bei einem Backup wird die Datenbank auf TOAST-Fehler und fehlende LOB Daten überprüft. Anstelle eines vollen Backups, kann die Datenbank auch gezielt auf Toast und LOB Fehler geprüft werden.

charly-server manage check-toast

Sollte die Postgres Version nicht automatisch gefunden werden, können Sie die Parameter manuell angeben:

charly-server manage check-toast -postgres_path /path/to/postgresql -postgres_port 5432

Ein finaler Export der Daten wird nur fehlerfrei möglich sein, wenn hier keine Fehler auftreten.

Dry-Run-Modus für Konfigurationsüberprüfung für den Export

Führen Sie zunächst auf dem alten Server einen Dry-Run-Export durch, um die Konfiguration zu überprüfen und mögliche Fehler zu identifizieren. Dies kann im laufenden Betrieb erfolgen:

charly-server export dryrun

Ein finaler Export der Daten wird nur möglich sein, wenn hier keine Fehler auftreten.

TIPP

Der Dry-Run versucht, alle möglichen Fehlerquellen zu identifizieren, die beim Export der Daten auftreten könnten. Es wird nur temporär eine ISO-Datei erstellt, damit diese später nicht fälschlicherweise verwendet wird. Es wird eine Log-Datei angelegt, in der alle gefundenen Probleme dokumentiert werden. Dafür überspringt der Dry-Run Fehler, um eine vollständige Übersicht über potenzielle Probleme zu erhalten.

Empfehlung:

  1. Sie können den DryRun auch während des laufenden Praxisbetriebs durchführen.
  2. Ermitteln Sie die Dauer des Dry-Runs aus der Log-Datei anhand der Timestamps (Anfang und Ende der Log-Datei).
  3. Planen Sie für den tatsächlichen Migrationsprozess etwa die gleiche Zeit ein (kein laufender Praxisbetrieb dabei möglich).

WICHTIG

Das Skript prüft, ob im charly-Ordner sehr viele unsichtbare Dateien existieren und gibt entsprechend eine Warnung aus. Die Dateipfade der unsichtbaren Dateien werden in einer Datei invisible_files.txt gespeichert und es erscheint eine Warnung.

Wenn Sie überflüssige Dateien entdecken und diese ein Schema haben, zB. .backupXYZ, dann könnten diese möglicherweise mit Vorsicht gelöscht werden via:

find /Applications/Solutio/Client/Charly/ -type f -name '.backup*' -delete

Aber auf keinen Fall '*' oder '.*' verwenden, da dies alle bzw. alle unsichtbaren Dateien löschen würde.

Konfiguration bei mehreren Mandanten

Wenn die klassische Installation mehrere Mandanten verwendet hat, muss die Konfiguration entsprechend angepasst werden:

  1. Mandanten prüfen
  2. Konfiguration in application.yml eintragen
  3. Container neu starten
  4. Konfiguration testen

Wenn nur ein Mandant verwendet wird, also der Standardfall, muss keine Anpassung vorgenommen werden.

1. Mandanten prüfen

Es muss geprüft werden, ob es mehrere Mandanten gibt. In diesem Fall entält die Datei Solutio.app/Mandanten.flg einen oder mehrere Einträge wie (Beispiel): 

1 767226552 Mandant 2

Außerdem muss es neben der Ablage auch Mandant2, möglicherweise Mandant3 und weitere geben.

2. Konfiguration eintragen

Status aufrufen, um den SMB Share zu finden:

charly-server vm status

Den SMB Share charly-config mit dem User smbadminuser und dem Administrator Passwort mounten (Siehe: Verbinden des Samba-Share "charly-config"). Darin findet sich die Datei conf2/_global/application.yml. In diese Datei folgendes eintragen.

Bei einem 2. Mandanten: 

de.solutio.tenant.ids: 1,2

de.solutio.tenant.names.1: tenant-1
de.solutio.tenant.names.2: tenant-2

de.solutio.charly.datasource.tenant2.host: database
de.solutio.charly.datasource.tenant2.username: postgres
de.solutio.charly.datasource.tenant2.password: ${POSTGRES_PASSWORD}
de.solutio.charly.datasource.tenant2.driver-class-name: org.postgresql.Driver
de.solutio.charly.datasource.tenant2.jdbc-url: jdbc:postgresql://${de.solutio.charly.datasource.tenant2.host}:${de.solutio.charly.datasource.tenant2.port}/${de.solutio.charly.datasource.tenant2.name}?ApplicationName=${spring.application.name}
de.solutio.charly.datasource.tenant2.name: solutiodb2
de.solutio.charly.datasource.tenant2.platform: postgresql
de.solutio.charly.datasource.tenant2.port: 5432
de.solutio.charly.filing.tenant2: /charly/mutable/Mandant2/Ablage

Bei einem 2. und 3. Mandanten: 

de.solutio.tenant.ids: 1,2,3

de.solutio.tenant.names.1: tenant-1
de.solutio.tenant.names.2: tenant-2
de.solutio.tenant.names.3: tenant-3

de.solutio.charly.datasource.tenant2.host: database
de.solutio.charly.datasource.tenant2.username: postgres
de.solutio.charly.datasource.tenant2.password: ${POSTGRES_PASSWORD}
de.solutio.charly.datasource.tenant2.driver-class-name: org.postgresql.Driver
de.solutio.charly.datasource.tenant2.jdbc-url: jdbc:postgresql://${de.solutio.charly.datasource.tenant2.host}:${de.solutio.charly.datasource.tenant2.port}/${de.solutio.charly.datasource.tenant2.name}?ApplicationName=${spring.application.name}
de.solutio.charly.datasource.tenant2.name: solutiodb2
de.solutio.charly.datasource.tenant2.platform: postgresql
de.solutio.charly.datasource.tenant2.port: 5432
de.solutio.charly.filing.tenant2: /charly/mutable/Mandant2/Ablage

de.solutio.charly.datasource.tenant3.host: database
de.solutio.charly.datasource.tenant3.username: postgres
de.solutio.charly.datasource.tenant3.password: ${POSTGRES_PASSWORD}
de.solutio.charly.datasource.tenant3.driver-class-name: org.postgresql.Driver
de.solutio.charly.datasource.tenant3.jdbc-url: jdbc:postgresql://${de.solutio.charly.datasource.tenant3.host}:${de.solutio.charly.datasource.tenant3.port}/${de.solutio.charly.datasource.tenant3.name}?ApplicationName=${spring.application.name}
de.solutio.charly.datasource.tenant3.name: solutiodb3
de.solutio.charly.datasource.tenant3.platform: postgresql
de.solutio.charly.datasource.tenant3.port: 5432
de.solutio.charly.filing.tenant3: /charly/mutable/Mandant3/Ablage

3. Container neu starten

Die Container müssen neu gestartet werden, um die Konfiguration zu aktivieren:

charly-server vm docker-rebuild

4. Konfiguration testen

Starten Sie den charly-Client, melden Sie sich unter den Mandanten mit einem Benutzer an und prüfen Sie, ob der Web-Client geladen werden kann.

Reaktivieren des Altsystems

Wenn es bei der Installation charly-VM zu unerwarteten Problemen kommt, kann die alte Installation wieder reaktiviert werden.

charly-server export rollback

Sollte das Kommando nicht funktionieren, können Sie die klassische Installation auch manuell reaktivieren:

Zuerst suchen Sie im Logfile nach "PostgreSQL bin" und "PostgreSQL data" und notieren sich diese Pfade.

Setzen Sie die beiden Pfade im folgenden Befehl unter <bin pfad> und <data pfad> ein und führen Sie den Befehl aus, um die Datenbank wieder zu starten:

sudo -u SOLUTIOSQL <bin pfad>/pg_ctl start -D <data pfad>

Im Anschluss muss die alte Datenbank wieder aktiviert werden:

Je nachdem welche Pfade hier verwendet wurden:

sudo mv /Library/LaunchDaemons/postgresql-13.plist_off /Library/LaunchDaemons/postgresql-13.plist

sudo launchctl load -w /Library/LaunchDaemons/postgresql-13.plist

Die ncjs-Services müssen wieder aktiviert und gestartet werden. Navigieren Sie im Terminal in das entsprechende Verzeichnis und führen Sie die folgenden Befehle aus:

cd /Applications/Solutio/Server/ncjs

./acd.sh registerall

./acd.sh startall

Zuletzt muss der SMB-Share für das charly-Verzeichnis /Applications/Solutio/Client/Charly wieder angelegt werden. Gehen Sie dafür in die Systemeinstellungen unter "Freigaben" (Sharing) -> "Dateifreigabe" (File Sharing) und legen Sie für das Verzeichnis den SMB-Share wieder an.

Prüfen Sie, ob die alte, wiederhergestellte charly-Client Installation für Ihren Praxisalltag wieder funktioniert.

Version: 2.8.9

Datum: 20.11.2025