Betrieb der charly VM

Diese Anleitung beschreibt den Betrieb der charly VM unter macOS.

Der Betrieb der charly VM erfolgt nach der Installation.

WICHTIG

Das Kommando charly-server manage wurde durch charly-server vm ersetzt. Damit wird das Kommando zwischen Windows und macOS vereinheitlicht.

Umstellung von charly-vm.sh auf zentrales charly-server

Das alte Skript charly-vm.sh, welches in früheren VM Installation verwendet wurde, wird durch das neue charly-server Skript ersetzt.

Wenn Sie noch das alte Skript verwenden, laden Sie das Installations-Skript mit folgendem Befehl herunter:

curl -o charly-server-install.zsh https://charly-cdn-solutio.s3.amazonaws.com/release/macos/charly-server-install.zsh

WICHTIG

Das charly-server-install.zsh muss neben dem alten charly-vm.sh Skript liegen, damit das charly-server-install.zsh Skript die charly-vm.conf Konfigurationsdatei finden kann.

Also vor dem Download in das entprechende Verzeichnis wechseln oder nach dem Download die Skript-Datei verschieben.

Machen Sie das Skript ausführbar:

chmod +x charly-server-install.zsh

Dann installieren charly-server:

./charly-server-install.zsh

Jetzt steht charly-server zur Verfügung und kann in einem beliebigen Verzeichnis ausgeführt werden:

charly-server vm status

System Check

Neben dem allgemeinen Status kann auch ein detaillierter Bericht der laufenden VM erzeugt werden. Er enthält verschiedene Parameter, wie Speicherverbrauch und Festplattenplatz. Der Bericht ist unterteilt in Daten zur VM und zum macOS Host.

Er kann jederzeit mit folgendem Befehl erstellt werden:

charly-server vm system-check

Der System Check kann auch in JSON-Form erstellt werden:

charly-server vm system-check json

Die Status-Daten sind:

VM

CPU Auslastung
Speicher Auslastung
Dateisystem Auslastung
Laufwerks-Mounts (charly-files, charly-data mit Groesse und Belegung)
SMB Server Status (Service und Port-Verfuegbarkeit)
Datenbank-Verbindung (Container-Status und Port-Erreichbarkeit)
Docker Container Status inklusive Anzeige der Container die nicht sauber laufen
Konnektor Verbindungsprüfung, sofern vorhanden
Kim Verbindungsprüfung, sofern vorhanden
Backup SMB-Verbindungsprüfung, sofern vorhanden

macOS

Infos zur macOS Version
CPU Auslastung
Speicher Auslastung
Größe und Dateisystem Auslastung der VM Images
SMB-Verbindungsprüfung des charly-ablage SMB Shares
Datenbank-Verbindungspruefung vom Host zur VM

Netzwerk-Diagnose

Um Netzwerkprobleme zu diagnostizieren oder die Konfiguration zu validieren, können Sie den integrierten Netzwerk-Test verwenden:

charly-server vm test-network

Getestete Komponenten

Dieser Befehl testet automatisch:

Netzwerk-Konfiguration: IP-Adresse, Gateway und DNS-Server
Grundlegende Konnektivität: Erreichbarkeit von Gateway, DNS und Internet
TI-Routing: RU/PU-Routen und TI-Endpunkte
Konnektor-Verbindungen: Konnektivität zu konfigurierten Konnektoren
KIM-Verbindungen: POP3/SMTP-Endpoints für KIM-Dienste

Ausgabe-Bereiche

Die Ausgabe ist strukturiert aufgebaut und zeigt:

Netzwerk-Konfiguration: IP, Gateway, DNS
Verbindungstests: Gateway, DNS, Internet
TI-Routing: RU/PU Routen, TI-Endpunkte
Konnektor-Verbindungen: Status und Details
KIM-Verbindungen: POP3/SMTP Status
Gesamtstatus: Erfolg oder Probleme

Anwendungsfälle

Nach Netzwerk-Änderungen: Validierung neuer IP-Konfigurationen
Bei Verbindungsproblemen: Schnelle Diagnose von TI- oder KIM-Ausfällen
Nach Konnektor-Konfiguration: Überprüfung der TI-Routing-Einrichtung
Regelmäßige Überprüfung: Sicherstellung der ordnungsgemäßen Funktion

Tipp

Verwenden Sie charly-server vm test-network nach Netzwerk-Änderungen oder bei Verbindungsproblemen zur schnellen Diagnose.

Logs sammeln

Mit dem get-logs Befehl können Sie alle relevanten Protokolldateien Ihrer VM-Installation automatisch sammeln - sowohl vom macOS-Host als auch von der Linux-VM.

# Logs auf Desktop sammeln (Host + VM)
charly-server vm get-logs

# Logs in benutzerdefiniertem Ordner sammeln
charly-server vm get-logs -export_path ~/Downloads

Wann zu verwenden

Vor Support-Kontakt zur umfassenden Fehleranalyse
Nach Updates bei Problemen
Bei VM-spezifischen Fehlern (Ansible, Backup, VPN)
Zur Dokumentation von Host- und VM-Zuständen

Was wird gesammelt

Der Befehl sammelt Logs von beiden Systemen:

macOS Host: - charly-Server Logs aus /usr/local/var/log/charly-server/ - PostgreSQL Logs (letzte 14 Tage)

Linux VM: - Ansible Logs (Update- und Konfigurationsprotokolle, letzte 7 Tage) - Backup-Logs (/var/log/charly_backup.log) - Solutio Service Logs - VPN-Logs (OpenVPN/WireGuard) - System-Logs (Samba, APT, Cloud-Init)

Alle Logs werden in ein einziges tar.gz-Archiv kombiniert (z.B. charly-logs-vm-20241114-153045.tar.gz) und auf dem Desktop gespeichert.

Ablauf

Host-Logs sammeln (macOS)
VM kontaktieren via SSH
VM-Logs sammeln und via SCP herunterladen
Host- und VM-Logs kombinieren
tar.gz-Archiv erstellen
Temporäre Dateien aufräumen

TIPP

Bei VM-Verbindungsproblemen werden zumindest die Host-Logs gesammelt
Das Archiv enthält keine Patientendaten
Automatische Bereinigung auf Host und VM
Archive können mit Doppelklick oder tar -xzf dateiname.tar.gz extrahiert werden

WICHTIG

Stellen Sie sicher, dass die VM läuft und erreichbar ist. Prüfen Sie vorab mit charly-server vm status.

Backup und Restore

Das Backup der VM kann in ein SMB Share abgelegt werden. Dieses muss im Netzwerk verfügbar sein.

Es werden nur die neuesten acht Backups der Datenbank gespeichert. Ältere Backups werden automatisch gelöscht. Die Daten der Ablage werden in ein charly.7z komprimiert, welches stetig aktualisiert wird.

Zusätzlich wird optional eine ISO Datei mit den aktuellsten Backup Daten erzeugt. Mit dieser ISO Datei kann jederzeit die VM neu installiert werden. Ohne diese ISO Datei ist ein Wiederherstellen über den Restore Mechanismus möglich.

Backup-Varianten

Es gibt 2 Varianten ein Backup zu erstellen:

Variante	Beschreibung
Inkrementell Backup (advanced)	Ein modernes Backup-Verfahren, dass auf der Backup-Software Restic basiert und die letzten 31 Backups platzsparend sichert. Dieses ist das empfohlene Verfahren.
Einfaches Backup (simple)	Sichert die Datenbank eines Backups als .sql Dateien, die Dateien als charly.7z und die Konfiguration. Dieses Verfahren ist veraltet, funktioniert aber weiterhin.

Backup konfigurieren

Geben Sie einen Ordner auf einem Laufwerk mit ausreichend Speicherplatz frei und testen Sie dafür unter macOS, ob sich dass SMB Share verbinden lässt. Dieser Ordner kann auch ein NAS sein.

Führen Sie dann folgendes Kommando aus:

charly-server vm backup-config

Sie werden nach folgenden Informationen gefragt:

IP oder Hostname des SMB Servers
Name des SMB Shares, ggf. gefolgt vom Pfad innerhalb des Shares (z.B. <ShareName>/<Pfad>)
Benutzername und Passwort für den SMB-Zugriff (falls erforderlich)
SMB-Version (optional, z.B. 2.0 für ältere NAS-Systeme)
Stunde (0-23) und Minute (0-59) für das tägliche Backup
Ob bei täglichen Backups zusätzlich ISO-Dateien erstellt werden sollen

Nach Eingabe der Information wird geprüft, ob die VM das SMB Share verbinden kann und ob der angegebene Benutzer darauf Schreibrechte besitzt. Ansonsten bricht das Kommando mit einer Fehlermeldung ab.

backup-config kann jederzeit wieder ausgeführt werden, um die Konfiguration zu ändern. Die bisherigen Daten erscheinen dann in der Eingabe (außer dem Passwort).

WICHTIG

Wenn bei einer Installation noch das charly-backup.qcow2 konfiguriert wurde, kann mit backup-config auf das neue Backup System umgestellt werden. Dann wird backup-config zusätzliche Hinweise anzeigen und die VM während der Einrichtung des Backups einmal neu starten. Zum Schluss können Sie das charly-backup.qcow2 löschen

SMB-Versionsunterstützung

Das charly-Server-System unterstützt die explizite Konfiguration von SMB-Protokollversionen für die Kompatibilität mit verschiedenen Netzwerkspeichern:

Unterstützte SMB-Versionen: - SMB 2.0 - Für ältere NAS-Systeme, Server und restriktive Konfigurationen - SMB 2.1 - Erweiterte Funktionen gegenüber 2.0 - SMB 3.0 - Moderne Systeme mit verbesserter Sicherheit - SMB 3.02 - Erweiterte Verschlüsselung - SMB 3.0.2 - Alternative Notation für 3.02 - SMB 3.1.1 - Neueste Sicherheitsfeatures - SMB 3.11 - Alternative Notation für 3.1.1

Wann eine SMB-Version angeben: - Bei Verbindungsproblemen mit älteren NAS-Systemen - Wenn der automatische Verhandlungsprozess fehlschlägt - Bei Server-Konfigurationen, die keine Auto-Verhandlung unterstützen - Zur Optimierung der Verbindungsgeschwindigkeit - Bei Sicherheitsanforderungen für spezifische Protokollversionen - Bei restriktiven Server-Sicherheitsrichtlinien

Empfohlene Vorgehensweise: 1. Zuerst ohne SMB-Version versuchen (automatische Verhandlung) 2. Bei Problemen mit älteren Systemen oder Server-Konfigurationen SMB 2.0 oder 2.1 verwenden 3. Für moderne Systeme SMB 3.0 oder höher bevorzugen 4. Bei anhaltenden Verbindungsproblemen verschiedene Versionen systematisch testen

Manuelles Backup erstellen

Ein manuelles Backup kann nach der Konfiguration jederzeit erstellt werden, indem in einem Terminal folgendes ausgeführt wird:

charly-server vm backup

Um beim Backup auch zusätzlich eine ISO Datei zu erzeugen, steht alternativ auch Folgendes bereit:

charly-server vm backup-iso

Das sind auch genau die Kommandos, die vom täglichen Backup verwendet werden, je nachdem, ob ein ISO erzeugt werden soll oder nicht.

Liste aller Backups

Es können die letzten 10 Backups angezeigt werden:

charly-server vm backup-list

Es können auch mehr oder weniger Backups angezeigt werden:

charly-server vm backup-list -count 20

Es können auch die Größen der Backups angezeigt werden. Dies sollte man aber nur mit wenigen Backups machen, da es sonst länger dauert:

charly-server vm backup-list -count 3 -show_sizes

Backup wiederherstellen

WICHTIG

Alle charly-Clients sollten beendet werden, bevor das Backup wiederhergestellt wird.
Alle Änderungen in der Datenbank und in der Ablage, die seit dem Backup erzeugt wurden, gehen durch die Wiederherstellung verloren.

Basierend auf den vorhandenen Backups im SMB Share kann ein Backup wiederhergestellt werden.

Das neueste Backup kann wiederhergestellt werden, indem in einem Terminal folgendes ausgeführt wird:

charly-server vm restore

Es kann auch ein spezifisches Backup wiederhergestellt werden. Es erscheint eine Auswahl der verfügbaren Backups.

Das Kommando wird die Ablage, die Config und das Datenbank-Backup einspielen und danach die Docker-Container wieder starten.

Update des Servers

Wenn eine neue Version der charly-Services verfügbar ist, kann diese manuell installiert werden.

WICHTIG

Alle charly-Clients sollten beendet werden, bevor das Update durchgeführt wird.

Führen Sie dazu folgendes Kommando aus:

charly-server vm update

Während des Updates wird ein Backup der Datenbank, der Solutio Ablage und der internen Server-Konfiguration erstellt. Das Update kann einige Zeit in Anspruch nehmen

Rollback eines Updates

WICHTIG

Alle charly-Clients sollten beendet werden, bevor das Rollback durchgeführt wird.
Alle Änderungen in der Datenbank und in der Ablage, die seit dem letzten Update erzeugt wurden, gehen durch das Rollback verloren.

Sollte das Update nicht korrekt funktionieren, kann es zurück gerollt werden, indem in einem Terminal folgendes ausgeführt wird:

charly-server vm update-rollback

IP-Konfiguration

Die IP-Konfiguration der charly VM kann über das ip-config Kommando angepasst werden. Diese Funktion ermöglicht es, die Netzwerk-Einstellungen der VM zu ändern, einschließlich IP-Adresse, Gateway und DNS-Server.

Windows Administrator Powershell:

charly-server vm ip-config

Funktionen des charly-vm Skripts

Wenn das Skript direkt ohne Parameter ausgeführt wird, erscheint eine Liste möglicher Parameter.

Usage: charly-server vm [<Befehl>] [Optionen]

Befehle:
  update               - Startet das Update der VM
  status               - Information zur VM, IP etc.
  start                - Startet die VM
  stop                 - Stoppt die VM
  docker-restart       - Restart der Docker Container in the VM (docker stop/start)
  docker-rebuild       - Baut die Docker Container in the VM erneut auf (docker down/up)
  backup-list          - Zeigt die Zeitstempel der verfügbaren Backups an.
  backup               - Erzeugt ein backup
  restore              - Stellt das neueste Backup wieder her.
  restore <timestamp>  - Stellt ein spezifisches Backup wieder her.
                         Nutze './charly-server vm backup-list' für eine Liste mit Zeitstempeln der verfügbaren Backups.
  update-rollback      - Rollback des letzten Updates
  ssh                  - SSH Zugang in die VM.
  ssh -C <command>     - Führt das <command> in der VM aus.
  change-password [ssh|postgres|admin|smb] - Ändert Passwörter der VM (interaktive Auswahl ohne Parameter)
  uninstall            - Deinstalliert die VM und optional die zugehörige Software
  logs [-f] <servicename> - Zeigt die Docker Container Logs an. Optional kann ein Servicename angegeben werden. Mit -f werden die Logs kontinuierlich angezeigt.

Folgende Parameter stehen beim charly-server Skript zur Verfügung:

Parameter	Beschreibung
install	Fragt die Konfiguration ab und installiert eine neue VM. Dieses Kommando wird typischerweise nur einmal ausgeführt. Es kann aber, ohne Datenverlust, bei Problemen mit der VM jederzeit wieder ausgeführt werden. Siehe Installation der charly-VM
vm update	Aktualisiert eine bestehende VM. Siehe Update der Service
vm update-rollback	Rollt das letzte Update zurück. Siehe Update der Service
vm status	Gibt Auskunft über den Zustand der VM; unter Anderem die IP-Adresse und den Zustand der Docker Container
vm start	Startet die VM, sofern sie noch nicht gestartet ist
vm stop	Stoppt die VM, sofern sie gestartet ist
vm docker-restart	Führt einen Neustart der Docker Container durch. Dies kann hilfreich sein, sollten nicht alle Docker-Container korrekt funktionieren
vm backup-list	Zeigt eine Liste aller verfügbaren Backups an. Siehe Backup und Restore der Datenbank
vm backup	Führt ein manuelles Backup durch. Siehe Backup und Restore der Datenbank
vm restore	Stellt das neueste Backup wieder her. Siehe Backup und Restore der Datenbank
vm restore <timestamp>	Stellt ein bestimmtes Backup wieder her. Siehe Backup und Restore der Datenbank
vm ssh	Login in die VM. Es sollte der Prompt `charly@charlyvm:~$` erscheinen. Dies ist typischerweise nur für die technische Administration der VM notwendig
vm ssh -C <command>	Anstatt sich via `ssh` auf die VM einzuloggen, kann auch ein Befehl direkt in der VM ausgeführt werden. Z.B. `./charly-server vm ssh -C "ls -la /"` zeigt den Inhalt des Verzeichnisses `/` der VM detailliert an.
vm change-password	Ändert Passwörter der VM (ssh, postgres, admin, smb). Siehe Passwort-Management

SSH-Zugriff und Sicherheit

Für das korrekte Funktionieren des charly-vm Skriptes nach einer Installation ist ein SSH Schlüssel notwendig, welcher nur für den Benutzeraccount zugänglich ist, unter dem die Installation durchgeführt wurde. Der SSH-Schlüssel wird im .ssh-Verzeichnis im VM Basisverzeichnis des jeweiligen Benutzerkontos gespeichert.

Bewahren Sie den SSH-Schlüssel sicher auf.
Bei einem Wechsel des Administrators muss der neue Administrator Zugriff auf den SSH-Schlüssel erhalten.
Sollte der SSH-Schlüssel verloren gehen, ist ein Eingriff des solutio-Supports mittels Online Termin erforderlich, um den Zugriff wiederherzustellen.
Um Ausfallzeiten zu vermeiden, planen Sie den Administratorwechsel sorgfältig und stellen Sie sicher, dass der SSH-Schlüssel ordnungsgemäß übergeben wird.

Admin Web-Interface

Die charly-VM bietet ein Web-Interface mit verschiedenen Funktionen an. Geben Sie dafür einfach die IP-Adresse der charly-VM in einen Browser ein.

Die IP-Adresse kann ermitteln werden, indem in einem Terminal folgendes ausgeführt wird:

charly-server vm status

Das Admin Web-Interface bietet folgende Funktionalitäten:

Name	Beschreibung
Status	Zeigt den Status der Services und weitere Systeminformationen an
Logfiles	Zeigt den Status der Docker Container und deren Logfiles an
PGAdmin	PGAdmin ist ein Admin Web-Interface der PostgreSQL Datenbank
Downloads	Es werden verschiedene Dateien zum Download angeboten. Hauptsächlich handelt es sich um Skripte zum Installieren des charly-Clients

Im Bereich Logfiles und PGAdmin muss eine Anmeldung erfolgen. Verwenden Sie die Administrator eMail und das Administrator Passwort, die Sie bei der Installation angegeben haben.

charly-config

Um eine Lizenz für eine Online Terminvergabe (OTV) zu hinterlegen oder Java-Services speziell zu konfigurieren, können spezifische Dateien in einem charly-config Samba-Share angelegt werden.

Öffnen Sie den Finder.
Gehen Sie im Menü auf "Gehe zu" und wählen Sie "Mit Server verbinden..." oder drücken Sie Command + K.
Geben Sie die SMB-Adresse ein, die von charly-server vm status angegeben wird.
Klicken Sie auf "Verbinden".
Wählen Sie "Als Registrierter Nutzer anmelden", Verwenden Sie "smbadminuser" als Name und das Administrator Passwort, das Sie bei der Installation angegeben haben.
Klicken Sie auf "Verbinden".

OTV

Dr. Flex

Bei der Installation des Online-Terminvergabesystems (OTV, Dr. Flex) führen Sie folgende zusätzliche Schritte durch:

Bearbeiten Sie auf dem Smb-Share charly-config (Siehe oben) die Datei docker.conf. Fügen sie ein:

DR_FLEX_AUTH_TOKEN=Platzhalter-Token

Hinweise

Stellen Sie sicher, dass Sie den Platzhalter-Token durch den korrekten kundenspezifischen Token ersetzen.

Danach führen Sie eine Aktualisierung der Docker-Container mittels aus:

charly-server vm docker-rebuild

Diese Schritte sollten die Dr. Flex OTV-Installation abschließen und den Dr. Flex Container starten.

conf2 - Java Service Konfiguration

Im Samba-Share "charly-config" gibt es einen Ordner "conf2", über den Sie spezifische Konfigurationen für einzelne Java-Services oder global für alle Services hinterlegen können. Diese Anleitung beschreibt, wie Sie Konfigurationsdateien erstellen und bearbeiten.

Ordnerstruktur

Die conf2-Struktur ermöglicht zwei Arten von Konfigurationen:

smb://<VM-IP>/charly-config/conf2/
├── _global/              # Globale Konfiguration für alle Services
│   └── application.yml   # Standardkonfiguration (wird überschrieben)
├── auth/                 # Service-spezifische Konfiguration
│   └── application.yml   # Überschreibt _global für auth
├── ehealth-gateway/      # Service-spezifische Konfiguration
│   └── application.yml   # Überschreibt _global für ehealth-gateway
├── gateway/
│   └── application.yml
└── query/
    └── application.yml

Verfügbare Service-Namen: auth, ehealth-gateway, gateway, query, und weitere Java-Services

Konfigurationspriorität

Service-spezifische Konfigurationen (ehealth-gateway\application.yml) überschreiben globale Konfigurationen (_global\application.yml).

Voraussetzungen

Bevor Sie Konfigurationsdateien erstellen oder bearbeiten:

Samba-Share verbunden: Siehe Abschnitt "Verbinden des Samba-Share 'charly-config'" oben
Administrator-Zugang: Sie benötigen smbadminuser mit dem Admin-Passwort
Backup empfohlen: Erstellen Sie vor Änderungen eine Kopie bestehender Konfigurationsdateien

Service-spezifische Konfiguration erstellen

Folgen Sie diesen Schritten, um eine service-spezifische application.yml zu erstellen:

Öffnen Sie den Finder und verbinden Sie sich mit dem Samba-Share (falls noch nicht verbunden):
- Menü "Gehe zu" → "Mit Server verbinden..." (Command + K)
- SMB-Adresse aus charly-server vm status eingeben
- Als smbadminuser mit Admin-Passwort anmelden
Navigieren Sie zum conf2-Ordner im verbundenen charly-config Share
Erstellen Sie einen neuen Ordner mit dem exakten Namen des Services (z.B. ehealth-gateway)
- Rechtsklick → "Neuer Ordner"
- Ordnernamen eingeben (z.B. ehealth-gateway)
WICHTIG

Der Ordnername muss exakt dem Service-Namen entsprechen (Groß-/Kleinschreibung beachten!)
Öffnen Sie den neu erstellten Ordner (z.B. ehealth-gateway)
Erstellen Sie eine neue Textdatei mit dem Namen application.yml
- Öffnen Sie TextEdit oder einen anderen Texteditor
- Erstellen Sie ein neues Dokument
- Speichern Sie es als application.yml im Service-Ordner
Bearbeiten Sie die Datei mit einem Texteditor Ihrer Wahl:
- TextEdit (vorinstalliert auf macOS)
- Visual Studio Code (empfohlen für YAML)
- BBEdit oder Sublime Text
Fügen Sie die gewünschte Konfiguration ein. Beispiel für Log-Level Erhöhung:
```
logging:
  level:
    de.solutio: DEBUG
```
YAML-Syntax
- Achten Sie auf korrekte Einrückung (2 Leerzeichen pro Ebene, keine Tabs!)
- Nach dem Doppelpunkt muss ein Leerzeichen folgen: key: value
- Strings mit Sonderzeichen in Anführungszeichen setzen
Speichern Sie die Datei mit UTF-8 Kodierung
- In TextEdit: "Format" → "In Normaltext umwandeln", dann speichern
- In VS Code: Unten rechts auf "UTF-8" achten
- Stellen Sie sicher, dass die Datei als .yml und nicht als .txt gespeichert wird
- macOS-spezifischer Pfad für globale Konfiguration: smb://<VM-IP>/charly-config/conf2/_global

TextEdit-Warnung

TextEdit speichert Dateien standardmäßig im Rich-Text-Format (.rtf). Verwenden Sie immer "Format" → "In Normaltext umwandeln" bevor Sie speichern, um eine korrekte .yml Datei zu erstellen.

Globale Konfiguration (_global)

Um eine Konfiguration für alle Java-Services zu setzen, navigieren Sie zum _global Ordner im conf2-Verzeichnis, erstellen oder bearbeiten Sie die Datei application.yml und fügen Sie die gewünschte Konfiguration hinzu.

Wann _global verwenden?

Für systemweite Einstellungen (z.B. Log-Level, Zeitzone)
Als Standard-Fallback für alle Services
Beachten: Service-spezifische Konfigurationen haben Vorrang!

Konfiguration anwenden

Nach dem Erstellen oder Bearbeiten einer application.yml müssen die Änderungen angewendet werden:

Option 1: VM Update (empfohlen, sicherste Methode)

charly-server vm update

Option 2: Docker-Container Neustart (schneller, weniger gründlich)

charly-server vm docker-restart

Produktive Umgebung

Während des Updates/Neustarts ist der CharlyServer nicht verfügbar. Planen Sie ein Wartungsfenster!

Häufige Fehler und Lösungen

Problem	Ursache	Lösung
Konfiguration wird nicht geladen	Dateiname falsch (z.B. `.yml.txt`)	Dateiendung prüfen, korrekt als `.yml` speichern
Service startet nicht	YAML-Syntax-Fehler	YAML-Syntax prüfen (Einrückung, Doppelpunkte)
"Zugriff verweigert" beim Speichern	Falsche Anmeldedaten	Als `smbadminuser` mit Admin-Passwort anmelden
Änderungen werden nicht übernommen	Kein Neustart durchgeführt	`charly-server vm update` ausführen
Falscher Service-Ordner	Tippfehler im Ordnernamen	Ordnername muss exakt mit Service-Namen übereinstimmen

Best Practices

Empfehlungen

Immer Backup erstellen vor Änderungen an bestehenden Konfigurationen
Test-Umgebung nutzen für neue Konfigurationen, bevor Sie diese produktiv einsetzen
YAML-Validator verwenden (z.B. yamllint.com) vor dem Speichern
Dokumentation pflegen: Notieren Sie sich, welche Konfigurationen Sie warum geändert haben
Minimale Konfiguration: Nur die notwendigen Properties überschreiben, nicht die gesamte Konfiguration duplizieren
Service-Namen genau prüfen: Bei Unsicherheit mit charly-server vm status die verfügbaren Services anzeigen lassen

Time-Server für eHealth-Gateway konfigurieren

Erstellen Sie eine application.yml im ehealth-gateway Service-Ordner:

de.solutio.ncjs.ehealth.infrastructure.time-sync-addresses: 192.168.172.1

Nach dem Speichern wenden Sie die Konfiguration mit charly-server vm update an.

charly Termine App aktivieren

Die charly Termine App synchronisiert Termine über WebDAV mit externen Kalendern.

Minimale Konfiguration (vorausgesetzt Sie haben bereits: Mandant-ID, WebDAV-URL, Benutzername und Passwort):

Erstellen Sie eine application.yml im gateway Service-Ordner:

de.solutio.termine:
  enabled: true
  instances:
    meinkalender:
      enabled: true
      tenant: 1
      webdav:
        server: https://webdav.example.com/calendars/
        username: kalender-user
        password: kalender-passwort

Nach dem Speichern wenden Sie die Konfiguration mit charly-server vm update an.

Mehrere Kalender

Sie können mehrere Instanzen definieren, indem Sie zusätzliche Blöcke unter instances hinzufügen (z.B. meinkalender, kalender2, usw.). Jede Instanz kann einen eigenen Mandanten und WebDAV-Server haben.

Erweiterte Optionen: Content-Filter, Blacklist/Whitelist, Synchronisations-Intervall und weitere Details finden Sie in der offiziellen Termine-App Dokumentation.

Weitere Beispiele

Beispiel: Datenbank-Verbindungspool konfigurieren

spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5

Beispiel: Globale Zeitzone setzen (_global)

spring:
  jackson:
    time-zone: Europe/Berlin

Version: 2.8.7

Datum der letzten Aktualisierung: 19.11.2025

macOS-spezifische Fehler:

Problem	Ursache	Lösung
Datei als .txt gespeichert	TextEdit-Standardformat	"Format" → "In Normaltext umwandeln" vor dem Speichern

macOS-spezifische Best Practice:

TextEdit-Format

Immer "In Normaltext umwandeln" verwenden, um Rich-Text-Formatierung zu vermeiden

Troubleshooting

Speicherlimits für Docker-Container

Falls Sie individuelle Arbeitsspeicher-Limits nutzen, können Sie diese im folgenden Format in die Datei docker.conf im Samba-Share "charly-config" eintragen:

Der Standard ist wie folgt, tragen Sie nur ein, was davon abweicht:

QUERY_MEMORY_LIMIT=1280M
EHKP_MEMORY_LIMIT=4096M
GHOSTSCRIPT_MEMORY_LIMIT=1024M
AZT_MEMORY_LIMIT=1024M
PDF_MEMORY_LIMIT=1024M
FHIR_WHIRE_MEMORY_LIMIT=1024M
EHEALTH_MEMORY_LIMIT=1280M
MEDICATION_MEMORY_LIMIT=1024M
EHEALTH_GATEWAY_MEMORY_LIMIT=3072M
DISCOVERY_MEMORY_LIMIT=1024M
GATEWAY_MEMORY_LIMIT=1024M
MESSAGING_MEMORY_LIMIT=1024M
ORCHESTRATION_MEMORY_LIMIT=512M
AUTH_MEMORY_LIMIT=1024M
FILES_MEMORY_LIMIT=256M
CDE_MEMORY_LIMIT=768M
RC_MEMORY_LIMIT=512M
APPHOSTING_MEMORY_LIMIT=512M
OLAP_MEMORY_LIMIT=1280M
APPS_MEMORY_LIMIT=768M
NFDM_MEMORY_LIMIT=512M
EMP_MEMORY_LIMIT=512M
NGINX_MEMORY_LIMIT=512M
DOZZLE_MEMORY_LIMIT=512M
PGADMIN_MEMORY_LIMIT=512M
FILESYSTEM_MEMORY_LIMIT=1024M
AI_GATEWAY_MEMORY_LIMIT=512M
AI_SPACY_SERVER_MEMORY_LIMIT=1536M
SOLUTIO_MEMORY_LIMIT=512M

Nach Änderungen an der Datei docker.conf muss ein Update ausgeführt werden, auch wenn charly bereits aktuell ist. Siehe dazu Update des Servers.

Beachten Sie, dass Sie ggf. höhere Limits benötigen, wenn Ihre Praxis zusätzliche Mitarbeiter beschäftigt.

Keine Verbindung per SSH in die VM möglich

Wenn unter per SSH nicht mehr in die VM eingeloggt werden kann, sind zu viele Schlüssel im SSH-Agent hinterlegt, die nicht für diese VM verwendet werden.

Received disconnect from 192.168.2.198 port 22:2: Too many authentication failures
Disconnected from 192.168.2.198 port 22

Lösung hierfür:

Befehl	Beschreibung
ssh-add -l	Zeigt alle Schlüssel an
ssh-add -D	Löscht alle hinterlegten Schlüssel
ssh-add -d \<key>	Löscht einen einzelnen Schlüssel aus der Liste

Die Container VM hat durch einen Neustart eine neue IP Adresse bekommen

Eigentlich sollte die Container VM vom DHCP Server immer die gleiche IP Adresse bekommen. Falls das nicht so ist, kann die Container VM durch einen Neustart eine andere IP zugewiesen bekommen. Dann funktionieren die charly-Clients nicht mehr, weil sie versuchen, sich mit der alten IP Adresse zu verbinden.

Führen Sie folgendes Kommando aus:
```
charly-server vm docker-rebuild
```
Löschen Sie auf den Arbeitsplätzen die charly.app und laden Sie den Client von der Admin Website wieder herunter. Die URL zur Admin-Website finden Sie via:
```
charly-server vm status
```

Der Solutio Client startet nicht

Wenn mehrere Installationen von Solutio.app auf dem System vorhanden sind, kann es zu Fehlern beim Start der Anwendung kommen, da macOS nicht eindeutig erkennen kann, welche Installation verwendet werden soll.

Diagnose: Alle Solutio.app Installationen finden:

mdfind 'kMDItemFSName == "Solutio.app"'

Lösung:

Führen Sie den obigen mdfind-Befehl aus, um alle Solutio.app Installationen zu lokalisieren
Entfernen Sie alle gefundenen Solutio.app Installationen
Löschen Sie anschließend die charly.app, die den Fehler zeigt
Starten Sie charly.app neu - eine frische Solutio.app wird automatisch heruntergeladen

Nach dem Neustart sollte nur noch eine einzige, funktionierende Solutio.app Installation vorhanden sein.

Passwort-Management

Es gibt einige Passwörter für die VM, die geändert werden können. Die Änderung sollte nur außerhalb der Praxis-Öffnungszeiten durchgeführt werden.

Passwort	Beschreibung
SSH Key	Die Passphrase des SSH Schlüssels womit sich `charly-server` mit der VM verbindet
Postgres	Passwort für die Postgres Datenbank
VM Admin	Passwort für das Anmelden im PgAdmin und den Logfile Bereich der Admin Webseite und für das `charly-config` SMB Share.
SMB	Passwort für das `charly-ablage` SMB Share

WICHTIG

Wenn mehrere Passwörter geändert werden, sollte nach jeder einzelnen Änderung getestet werden!

Neues Passwort-Management (empfohlen)

Seit Version 2.5.0 steht ein neues, vereinfachtes Passwort-Management zur Verfügung:

charly-server vm change-password

Dieses Kommando bietet folgende Vorteile:

Interaktive Auswahl: Ohne Parameter wird ein Menü angezeigt
Direkte Passwort-Typen: ssh, postgres, admin, smb
Automatische Synchronisation: Neue Passwörter werden in credentials.txt gespeichert

Verfügbare Passwort-Typen

charly-server vm change-password ssh      # SSH-Schlüssel Passphrase
charly-server vm change-password postgres # PostgreSQL Datenbankpasswort
charly-server vm change-password admin    # VM Administrator Passwort
charly-server vm change-password smb      # SMB-Share Passwort

Besonderheiten beim SSH-Schlüssel

Bei der SSH-Schlüssel Passphrase wird ein zweistufiger Prozess verwendet:

Eingabe der neuen Passphrase: Das aktuelle Passwort wird als Standardwert angezeigt
Interaktive Änderung: ssh-keygen wird interaktiv ausgeführt
Synchronisation: Die neue Passphrase wird in credentials.txt gespeichert

Nach der Passwort-Änderung

Nach der Änderung bestimmter Passwörter sind zusätzliche Schritte erforderlich:

SSH-Schlüssel Passphrase

Keine weiteren Schritte erforderlich: Die Änderung wird automatisch bei der nächsten Verwendung wirksam
Optional: Testen Sie die Verbindung mit charly-server vm status

PostgreSQL Passwort

Clients neu starten: Alle charly-Clients müssen neu gestartet werden
Die Clients erhalten automatisch das neue Passwort beim nächsten Start

VM Administrator Passwort

Webinterface: Verwenden Sie das neue Passwort für PgAdmin und Logfile-Bereich
SMB charly-config: Verwenden Sie das neue Passwort für das charly-config SMB-Share

WICHTIG - Client-Neuinstallation erforderlich

Nach der Änderung des SMB-Passworts müssen alle charly-Clients auf allen Arbeitsplätzen neu heruntergeladen und installiert werden!

Erforderliche Schritte auf jedem macOS-Arbeitsplatz:

Netzlaufwerk trennen: Trennen Sie das Netzlaufwerk zur Ablage
Client herunterladen: Laden Sie charly-client-mac.zip über das Webinterface herunter
Anwendung ersetzen: Ersetzen Sie die bestehende charly.app durch die neue Version

Grund: Der charly-Client speichert die SMB-Anmeldedaten lokal. Diese können nur durch das Ersetzen der Anwendung aktualisiert werden.

Tipp

Planen Sie SMB-Passwort-Änderungen außerhalb der Arbeitszeiten und informieren Sie alle Benutzer über die erforderliche Client-Neuinstallation.

Solutio Service

Der Solutio Service läuft nicht als Container sondern wird direkt in der Linux VM gestartet. Darum kann er nicht wie andere Docker container gestartet oder gestoppt werden.

Befehle

Statt dessen stehen für den solutio service die folgenden Befehle zur Verfügung:

Befehl	Beschreibung
charly-server vm solutio-service start	Startet den Solutio Service
charly-server vm solutio-service stop	Stoppt den Solutio Service
charly-server vm solutio-service restart	Startet den Solutio Service neu
charly-server vm solutio-service logs	Zeigt die Logs des Solutio Service an
charly-server vm solutio-service status	Zeigt den Status des Solutio Service an
charly-server vm solutio-service errorlogs	Zeigt die Error Logs des Solutio Service an

Version: 2.8.10

Datum der letzten Aktualisierung: 20.11.2025

Betrieb der charly VM

Umstellung von charly-vm.sh auf zentrales charly-server

System Check

VM

macOS

Netzwerk-Diagnose

Getestete Komponenten

Ausgabe-Bereiche

Anwendungsfälle

Logs sammeln

Wann zu verwenden

Was wird gesammelt

Ablauf

Backup und Restore

Backup-Varianten

Backup konfigurieren

SMB-Versionsunterstützung

Manuelles Backup erstellen

Liste aller Backups

Backup wiederherstellen

Update des Servers

Rollback eines Updates

IP-Konfiguration

Funktionen des charly-vm Skripts

SSH-Zugriff und Sicherheit

Admin Web-Interface

charly-config

Verbinden des Samba-Share "charly-config"

OTV

Dr. Flex

conf2 - Java Service Konfiguration

Ordnerstruktur

Voraussetzungen

Service-spezifische Konfiguration erstellen

Globale Konfiguration (_global)

Konfiguration anwenden

Häufige Fehler und Lösungen

Best Practices

Time-Server für eHealth-Gateway konfigurieren

charly Termine App aktivieren

Weitere Beispiele

Troubleshooting

Speicherlimits für Docker-Container

Keine Verbindung per SSH in die VM möglich

Die Container VM hat durch einen Neustart eine neue IP Adresse bekommen

Der Solutio Client startet nicht

Passwort-Management

Neues Passwort-Management (empfohlen)

Verfügbare Passwort-Typen

Besonderheiten beim SSH-Schlüssel

Nach der Passwort-Änderung

SSH-Schlüssel Passphrase

PostgreSQL Passwort

VM Administrator Passwort

SMB-Share Passwort

Solutio Service

Befehle