Container-Update: Nativ zu VM

Diese Anleitung beschreibt den Prozess der Migration einer bestehenden nativen charly-Server Installation auf eine neue charly-VM (Container-basierte Installation). Ziel ist es, die Ausfallzeit für die Praxis zu minimieren, indem Vorbereitungen während der Betriebszeiten getroffen werden.

Strategie: Effiziente Migration mit minimaler Ausfallzeit

Diese Anleitung fokussiert sich auf den empfohlenen Migrationspfad, der darauf abzielt:

Ausfallzeit zu minimieren: Der Großteil der Vorbereitung (Datenübertragung, VM-Installation) kann während der Praxiszeiten erfolgen.
Gesamtdauer zu verkürzen: Statt eine riesige ISO-Datei mit allen Daten zu erstellen, werden Datenbank und Dateien (Ablage etc.) getrennt und effizient über einen SMB Share übertragen. Das zeitaufwändige Kopieren der charly.7z-Datei findet im Hintergrund statt (transfer-files).
Arbeitszeit effizient zu nutzen: Viele Schritte auf dem Quell- und Zielsystem können parallel ausgeführt werden, was Wartezeiten reduziert. Das Kopieren der Ablage erfolgt ferner ohne menschliche Supervision.
Gezielte & schnelle Umstellung zu ermöglichen:
- Ein Vorabtest der VM-Installation und der grundlegenden Funktionalität ist mit einem schnellen Datenbank-Snapshot (export databaseiso) möglich.
- Die finale Umstellung (export migration) beschränkt sich auf den Export des letzten Datenbankstands und kleinerer Dateiänderungen auf den Share. Dies ist deutlich schneller als das Erstellen einer kompletten Migrations-ISO.
- Der anschließende Datenimport auf der Ziel-VM (vm restore/restore-files) ist ebenfalls optimiert.
- Ziel: Die kritische Umstellungsphase außerhalb der Praxiszeiten kann so, bei guter Vorbereitung und adäquater Hardware, oft in unter einer Stunde abgeschlossen werden.

Kernschritte der empfohlenen Strategie:

Vorbereitung (Während der Praxiszeiten):
- SMB Share einrichten.
- export databaseiso -> SMB Share (notwendig für VM-Installation).
- export transfer-files -> SMB Share (überträgt Hauptdaten charly.7z).
- Parallel: charly-server install auf Zielsystem (mit databaseiso).
- charly-server vm backup-config auf Zielsystem (nutzt SMB Share).
Finale Umstellung (Außerhalb der Praxiszeiten):
- charly-server export migration -> SMB Share (stoppt Quelle, exportiert finalen DB-Stand postgres.tar.gz, aktualisiert charly.7z). Erzeugt keine ISO mehr!
- charly-server vm restore / restore-files auf Zielsystem (importiert Daten vom Share).
- Finale Tests & Go-Live.

Alternativer Ablauf (NICHT empfohlen - höhere Ausfallzeit):

Notwendig, wenn keine Vorbereitung (kein früherer SMB-Zugriff, keine Zeit) oder keine parallele VM-Installation (RAM-Mangel auf Host) möglich ist.
charly-server export migration wird mit -ISOFilePath ausgeführt, um eine komplette Migrations-ISO lokal zu erstellen.
Diese große ISO muss manuell auf das Zielsystem oder den Share übertragen werden.
charly-server install kann erst danach mit dieser ISO erfolgen.
Dies verlängert die benötigte Ausfallzeit erheblich.

Voraussetzungen

Administrator-Zugriff auf den Quellserver (nativ) und den Zielserver (neue VM-Umgebung).
PowerShell ab Version 5.1 mit Administratorrechten auf beiden Systemen.
Ein SMB-Netzlaufwerk (Share), das von beiden Servern aus erreichbar ist und über ausreichend Speicherplatz für den Export und das Backup verfügt.
Netzwerkkenntnisse zur Einrichtung des SMB-Shares und ggf. zur Konfiguration fester IP-Adressen.
Ressourcen auf dem Quell-System (Host):
- Für den empfohlenen Ablauf mit VM-Installation vor der finalen Umstellung muss der Host des Quellsystems (falls die VM auf demselben Host laufen soll) über ausreichend freien Arbeitsspeicher verfügen (Richtwert: mindestens 32 GB zusätzlich zur laufenden nativen Installation), um die charly-VM parallel starten zu können.
- Dies gilt, wenn:
  - Das Zielsystem = Quellsystem ist (Migration auf demselben Server).
  - Das Quellsystem selbst eine VM ist und die neue charly-VM auf demselben Hyper-V-Host erstellt wird.
- Ist das Zielsystem eine dedizierte neue Hardware, entfällt diese spezifische RAM-Einschränkung für den Parallelbetrieb.

charly-Server-Skript

Stellen Sie sicher, dass das charly-server Skript auf beiden Systemen installiert und aktuell ist.

Prüfen der Installation:

charly-server

Wenn das Skript installiert ist, wird die Versionsnummer angezeigt. Ansonsten installieren Sie es:

Installation:

# Download des Installers
Invoke-WebRequest -Uri "https://charly-cdn-solutio.s3.amazonaws.com/release/windows/charly-server-install.ps1" -OutFile ".\charly-server-install.ps1"

# TLS 1.2 setzen (falls Download fehlschlägt)
# [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

# Ausführungsrichtlinie anpassen (falls nötig)
Set-ExecutionPolicy RemoteSigned -Force
# Bei Signaturproblemen:
# Set-ExecutionPolicy Unrestricted -Force

# Skript ausführen
.\charly-server-install.ps1

# Nach Abschluss ggf. zurücksetzen:
# Set-ExecutionPolicy RemoteSigned -Force

Wiederholen Sie die Installation auf dem Zielserver.

Migrations-Workflow mit parallelen PowerShell-Operationen

Die folgende Darstellung zeigt den Migrations-Workflow aufgeteilt in drei PowerShell-Fenster (QP1, QP2, ZP1) und illustriert, welche Schritte parallel ausgeführt werden können:

Schritt-für-Schritt Anleitung (Empfohlener Pfad)

Legende:

Q: Quellsystem (Nativer Charly-Server)
Z: Zielsystem (Hyper-V Host für die charly-VM)
QP1, QP2: PowerShell-Fenster 1 und 2 auf dem Quellsystem.
ZP1: PowerShell-Fenster 1 auf dem Zielsystem.
SMB Share: Zentrales Netzlaufwerk (UNC-Pfad: \\SERVERNAME\SHARENAME)

Setup:

Alle Systeme: Öffnen Sie die benötigten PowerShell-Fenster (QP1, QP2, ZP1) mit Administratorrechten.
Alle Systeme: Stellen Sie sicher, dass das charly-server-Skript installiert und aktuell ist (siehe Voraussetzungen).
Planung:
- Notieren Sie UNC-Pfad und Anmeldedaten für den SMB Share.
- Legen Sie die finale statische IP-Adresse für die neue charly-VM fest und prüfen Sie deren Verfügbarkeit (ping).
Zielsystem/Netzwerk: Richten Sie den SMB Share ein, stellen Sie Erreichbarkeit und ausreichenden Speicherplatz sicher.

Phase 1: Vorbereitung (Während der Praxiszeiten)

Ziel: Systeme prüfen, eine Test-DB-ISO erstellen, Hauptdaten (charly.7z) auf den Share übertragen, Ziel-VM installieren und Backup konfigurieren.

[ZP1] Zielsystem: Systemcheck.

# Prüft Hyper-V, Ressourcen etc.
charly-server check-system

[QP1] Quellsystem: Systemcheck.

# Prüft Konfiguration, Speicherplatz etc.
charly-server check-system

[QP2] Quellsystem: Datenbank-Test-ISO exportieren:
- Zweck: Ermöglicht eine frühe Installation und Test der VM auf dem Zielsystem.
- Ausführung: Kann während des Praxisbetriebs erfolgen.
```
# Exportiert DB-Snapshot als ISO direkt auf den Share
charly-server export databaseiso -ExportPath "\\SERVERNAME\SHARENAME" -ISOFilePath "\\SERVERNAME\SHARENAME\database.iso"
```
- Nach Abschluss des Exports werden Netzwerkfreigabe-Informationen angezeigt, einschließlich des UNC-Pfads und des mount-backup-drive Befehls für das Zielsystem.
[QP2] Quellsystem: Charly-Dateien übertragen:
- Zweck: Überträgt den Großteil der Daten (Ablage etc.) als komprimiertes charly.7z-Archiv auf den SMB Share. Minimiert die Datenmenge für export migration.
- Ausführung: Kann während des Praxisbetriebs erfolgen. Aktualisiert eine eventuell vorhandene charly.7z-Datei.
  
  Dieser Befehl erstellt bzw. aktualisiert charly.7z auf dem Share
```
charly-server export transfer-files -ExportPath "\\SERVERNAME\SHARENAME"
```
  5. (Parallel zu 3 & 4) [ZP1] Zielsystem: SMB-Share mounten und VM-Installation starten: * Voraussetzung: Genügend RAM auf dem Host des Zielsystems (siehe Voraussetzungen), falls Ziel = Quelle oder beide VMs auf demselben Host liegen. * SMB-Share mounten:
  
  Mountet den SMB-Share vom Quellsystem (der exakte Befehl wird nach export databaseiso angezeigt. Diesen bitte kopieren anstelle des Beispiels hier)
```
charly-server export mount-backup-drive -UNCPath "\\SERVERNAME\SHARENAME"
```
  * Wichtig: Sie müssen den SMB-Share in einer Administrator-PowerShell mounten, da die VM-Installation ebenfalls mit Administrator-Rechten ausgeführt wird. Ein Mount als normaler Benutzer ist für die Installation nicht ausreichend, da die Laufwerkszuordnungen pro Benutzer gelten und in der Administrator-Umgebung nicht sichtbar wären. * Installation mit DB-Test-ISO:
  
  Startet Installation mit DB-Snapshot vom gemounteten Share. Verwenden Sie den Laufwerksbuchstaben, der beim mount-backup-drive angezeigt wurde (z.B. E:) oder direkt den UNCPath.
```
charly-server install -PathFilesISO "\\SERVERNAME\SHARENAME\database.iso"
```
  * Folgen Sie den Anweisungen. Geben Sie die finale, geplante IP-Adresse an. Notieren Sie sich das Admin-Passwort.
[ZP1] Zielsystem: Frühe Verifizierung durchführen:
- Browsertest: Prüfen Sie, ob http://<VM-IP> erreichbar ist und die Charly-Startseite angezeigt wird.
- PGAdmin: Verbinden Sie sich mit PGAdmin (Host: <VM-IP>, User: postgres) und prüfen Sie, ob in solutiodb.version die Lizenzdaten (anzahl, praxis) korrekt angezeigt werden.
- Client-Test: Laden Sie den Client herunter und prüfen Sie die Anmeldung.
[ZP1] Zielsystem: Backup konfigurieren:
- Zweck: Absolut notwendig für die Datensicherheit der neuen VM.
- Konfiguration: Nutzen Sie den SMB Share als Ziel.
```
charly-server vm backup-config
```
  Folgen Sie den Anweisungen (UNC-Pfad, Credentials, Zeitplan).

Phase 2: Finale Umstellung (Außerhalb der Praxiszeiten!)

Ziel: Quellsystem stoppen, finalen DB-Stand exportieren, Daten auf Ziel-VM wiederherstellen.
[QP1] Quellsystem: Finalen Migrations-Export starten:
- Zweck: Stoppt die native Installation, exportiert den letzten Stand der Datenbanken (postgres.tar.gz) und aktualisiert charly.7z auf dem SMB Share.
- WICHTIG: Benötigt Ausfallzeit für die Praxis! Exportiert finalen DB-Stand & aktualisiert charly.7z auf dem Share und erzeugt KEINE ISO mehr!
```
charly-server export migration
```
- Nach Abschluss des Exports werden Netzwerkfreigabe-Informationen angezeigt, einschließlich des UNC-Pfads und der auf dem Zielsystem zu verwendenden Anmeldeinformationen.
- Migrationsmodus
  - Stoppt Charly-Dienste und deaktiviert sie dauerhaft.
  - Kann je nach DB-Größe dauern.
[ZP1] Zielsystem: Daten wiederherstellen (Nach Abschluss von export migration):

Stellt finalen DB-Stand UND Dateien komplett wieder her
```
charly-server vm restore
```

Phase 3: Verifizierung & Abschluss

Ziel: Sicherstellen, dass die neue VM korrekt funktioniert.
[ZP1] Zielsystem: Status prüfen:
```
charly-server vm status
```
Stellen Sie sicher, dass die VM läuft und alle Container grün sind.
Verifizierung Teil 1 (Direkt nach restore):
- Browser: Prüfen Sie Dozzle (http://<VM-IP>:9001) und Eureka (http://<VM-IP>:8761).
- PGAdmin: Verbinden Sie sich erneut. Prüfen Sie solutiodb.version (sollte jetzt definitiv die korrekten Lizenzinfos enthalten) und ggf. andere Tabellen stichprobenartig.
Verifizierung Teil 2 (Client-Tests):
- Test-Arbeitsplatz: Installieren/Starten Sie den charly-client (Download von http://<VM-IP>).
- Anmeldung & Basistests: Prüfen Sie Login, DB-Version, Konnektor, KIM.
- Ablage: Überprüfen Sie unbedingt bei mehreren Patienten, ob Dokumente in der Ablage korrekt angezeigt werden.
(Optional) [ZP1] Zielsystem: IP-Adresse ändern: Nur falls unbedingt nötig.
```
charly-server vm ip-config
```
!!! warning "IP-Änderung" Erfordert Neuinstallation aller charly-clients!
Finale Tests: Führen Sie umfassende Tests auf mehreren Arbeitsplätzen durch.
Quellserver: Alte Installation entfernen: Erst wenn die neue VM mehrere Tage stabil und fehlerfrei läuft. Sichern Sie vorher alle Daten!

Rollback bei Fehlern:

Nur bevor produktiv mit der neuen VM gearbeitet wurde!

[QP1] Quellsystem: Dienste wieder starten !!! warning "Vorherige DB Migration mit mehreren PostgreSQL Verzeichnissen (zum Beispiel ein PostgreSQL13 + PostgreSQL Ordner)" In diesem Fall muss man ggf. den C:\Solutio\Server\PostgreSQL ordner umbennen in C:\Solutio\Server\PostgreSQL.VERYOLD damit das Skript den richtigen Ordner findet.
```
charly-server manage start
```
[ZP1] Zielsystem: Fehlgeschlagene Installation bereinigen
```
charly-server vm uninstall
```

Datenverlust bei Rollback nach Nutzung

Kontaktieren Sie bei Problemen nach produktiver Nutzung der VM umgehend den Support!

Konfiguration bei mehreren Mandanten

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

Mandanten prüfen
Konfiguration in application.yml eintragen
Container neu starten
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.charly.datasource.tenant2.host: database
de.solutio.charly.datasource.tenant2.username: postgres
de.solutio.charly.datasource.tenant2.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.charly.datasource.tenant2.host: database
de.solutio.charly.datasource.tenant2.username: postgres
de.solutio.charly.datasource.tenant2.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: 
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.

Wichtige Hinweise

Die Vorbereitung während der Praxiszeiten (export databaseiso, transfer-files) ist der Schlüssel zur Minimierung der Ausfallzeit.
export migration ist der kritische Schritt, der die Ausfallzeit bestimmt und das Quellsystem deaktiviert.
Der SMB Share ist zentral für den Datenaustausch und das Backup.
Die Backup-Konfiguration (vm backup-config) ist essentiell.
vm restore / restore-files sind notwendig, um die finalen Daten vom Share in die VM zu bringen.
Beachten Sie die RAM-Voraussetzungen für den Parallelbetrieb von Quellsystem und Test-VM auf demselben Host.
Die frühe Verifizierung nach der Installation mit database.iso ermöglicht es, Probleme zu identifizieren, bevor große Datenmengen (100GB+) übertragen werden.

Diese Anleitung bietet einen Überblick über den Migrationsprozess. Für detailliertere Informationen oder bei spezifischen Problemen wenden Sie sich bitte an den Support.

Version: 2.5.1

Datum der letzten Aktualisierung: 25.06.2025