Zum Inhalt

Betrieb der charly VM

Diese Anleitung beschreibt den Betrieb der charly VM unter macOS.

Der Betrieb der charly VM erfolgt nach der Installation.

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 vewenden, laden Sie das Installation-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 manage status

System Check

Neben dem allgemeinen Status kann auch ein datailierter 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 manage system-check

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

charly-server manage system-check json

Die Status-Daten sind:

VM

  • CPU Auslastung
  • Speicher Auslastung
  • Dateisystem Auslastung
  • 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 Shared

Backup und Restore der Datenbank

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

Es werden nur die neuesten acht Backups der Datebank 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 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 manage backup-config

Sie werden nach den Daten für das SMB Share gefragt. Sie werden auch gefragt, ob bei einem Backup auch ein ISO erzeugt werden soll. Zum Schluss geben Sie noch an, wann das tägliche Backup statt finden soll.

Nach Eingabe der Information wird geprüft, ob die VM das SMB Share verbinden kann und ob der angegebenen Beutzer 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 das 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

Manuelles Backup erstellen

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

charly-server manage backup

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

charly-server manage 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.

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 Wiederherstehlung 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 manage restore

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

Es kann auch ein spezifisches Backup wiederhergestellt werden.

Führen Sie zuerst folgendes Kommando aus, um eine Liste mit Zeitstempeln der verfügbaren Backups zu erhalten:

charly-server manage backup-list

Benutzen einen Zeitstempel für das restore Kommando, zB.:

charly-server manage restore 2023-10-12-10-22

Es kann auch auschließlich die Datenbank wiederhergestellt werden 

charly-server manage restore-database
bzw. 
charly-server manage restore-database 2023-10-12-10-22

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.zsh manage update

Während des Updates wird ein Backup der Datenbank und 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 letzem 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.zsh manage update-rollback

Funktionen des charly-vm Skripts

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

Usage: charly-server manage [<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 verfuegbaren Backups an.
  backup               - Erzeugt ein backup
  restore              - Stellt das neueste Backup wieder her.
  restore <timestamp>  - Stellt ein spezifisches Backup wieder her.
                         Nutze './charly-server.zsh manage backup-list' fuer eine Liste mit Zeitstempeln der verfuegbaren Backups.
  update-rollback      - Rollback des letzten Updates
  ssh                  - SSH Zugang in die VM.
  ssh -C <command>     - Fuehrt das <command> in der VM aus.
  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.zsh 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
manage update Aktualisiert eine bestehende VM. Siehe Update der Service
manage update-rollback Rollt das letzte Update zurück. Siehe Update der Service
manage status Gibt Auskunft über den Zustand der VM; unter Anderem die IP-Adresse und den Zustand der Docker Container
manage start Startet die VM, sofern sie noch nicht gestartet ist
manage stop Stoppt die VM, sofern sie gestartet ist
manage docker-restart Führt einen Neustart der Docker Container durch. Dies kann hilfreich sein, sollten nicht alle Docker-Container korrekt funktionieren
manage backup-list Zeigt eine Liste aller verfügbaren Backups an. Siehe Backup und Restore der Datenbank
manage backup Führt ein manuelles Backup durch. Siehe Backup und Restore der Datenbank
manage restore Stellt das neueste Backup wieder her. Siehe Backup und Restore der Datenbank
manage restore <timestamp> Stellt ein bestimmtes Backup wieder her. Siehe Backup und Restore der Datenbank
manage ssh Login in die VM. Es sollte der Prompt charly@charlyvm:~$ erscheinen. Dies ist typischerweise nur für die technische Administration der VM notwendig
manage 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.zsh manage ss -C "ls -la /" zeigt den Inhalt des Verzeichnisses / der VM detailiert an.

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.zsh manage 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.

Verbinden des Samba-Share "charly-config"

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

OTV

Im Samba-Share "charly-config" gibt es einen Ordner "otv-license". Hier kann die Lizenz-Datei abgelegt werden.

Dr. Flex

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

Kopieren Sie die Lizenz für die Online-Terminvergabe in das 'charly-config' Netzlaufwerk in den Ordner "otv-license".

Bearbeiten Sie auf dem admin smb share die Datei charly-config/docker-compose.overwrite.yml: 

services:
  dr-flex:
    image: drflex/charly-tunnel:latest
    environment:
      - QUERY_SERVICE_ADDRESS=http://gateway:
      - CONFIGURE_AUTH_TOKEN_WITH=????????????????????????????? (Hinweis: Der Token ist kundenspezifisch!)
Hinweise: * Fügen sie nur die Information über den Dr. Flex Service hinzu. * Stellen Sie sicher, dass Sie den Platzhalter-Token durch den korrekten kundenspezifischen Token ersetzen.

Danach führen Sie ein Update mittels sudo ./charly-server.zsh manage update aus, auch wenn charly bereits aktuell ist. Achten sie darauf, dass wärend dieses Vorgangs an charly nicht gearbeitet werden kann.

Diese Schritte sollten die Dr. Flex OTV-Installation abschließen und den Tunnel-Dienst in Ihrer Umgebung aktivieren.

conf2

Im Samba-Share "charly-config" gibt es einen Ordner "conf2". Hier können in Unterordnern, die nach den Kurznamen der Services benannt sind (auth, ehealth, etc.) jeweils eine Datei "application.yml" abgelegt werden, in der spezielle Java Konfigurationen konfiguriert werden.

Oder es kann im schon vorhandenen Unterordner "_global" solche eine Datei "application.yml" abgelegt werden, in der spezielle Java Konfigurationen konfiguriert werden. Diese Konfiguration gilt dann übergreifend für all Java Services und überschreibt auch andere Konfigurationen in "conf2".

docker.conf

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=2048M
EHKP_MEMORY_LIMIT=4096M
GHOSTSCRIPT_MEMORY_LIMIT=1024M
DIFFER_MEMORY_LIMIT=1024M
IDEA_MEMORY_LIMIT=1024M
PDF_MEMORY_LIMIT=1024M
EHEALTH_MEMORY_LIMIT=4096M
EHEALTH_GATEWAY_MEMORY_LIMIT=3072M
DISCOVERY_MEMORY_LIMIT=1024M
GATEWAY_MEMORY_LIMIT=2048M
MESSAGING_MEMORY_LIMIT=1024M
ORCHESTRATION_MEMORY_LIMIT=1024M
FILES_MEMORY_LIMIT=256M
Nach Änderungen an der Datei docker.conf muss ein Update ausgeführt werden, auch wenn charly bereits aktuell ist.

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

Troubleshooting

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.

  1. Führen Sie folgendes Kommando aus: 

    charly-server.zsh manage reapply-ip

  2. 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.zsh manage status

Version: 1.1.3

Datum: 2025-02-06