TRIAS - Triage- und Ambulanzsystem
=================================

ANLEITUNG FÜR WINDOWS 11

Diese Anleitung ist zur Erstellung und Testung des TRIAS-Systemes. Es führt das Programm lokal auf Ihrem Computer aus und ist nur zu Demonstrationszwecken gedacht.


1. WAS IST TRIAS?
-----------------

TRIAS ist ein lokal ausführbares Triage- und Ambulanzsystem. Es besteht aus
mehreren Teilen:

- der sichtbaren Webseite,
- dem Server, der die Daten verarbeitet,
- einer MySQL-Datenbank,
- einem Mosquitto-Nachrichtendienst.

Docker Desktop startet diese Teile gemeinsam in sogenannten Containern.
Sie müssen dafür weder eine Datenbank noch einen Webserver einzeln
installieren.

Die Anwendung läuft nach dem Start nur auf Ihrem Computer und ist im Browser
unter folgender Adresse erreichbar:

http://localhost:8080

WICHTIG:
Diese Anleitung startet die Entwicklungsumgebung für lokale Tests. Verwenden
Sie diese Konfiguration nicht ohne zusätzliche Sicherheitsprüfung als
öffentlich erreichbares Produktivsystem.


2. BEGRIFFE EINFACH ERKLÄRT
---------------------------

Repository:
Der Projektordner, der von GitHub auf Ihren Computer heruntergeladen wird.

PowerShell:
Ein in Windows eingebautes Fenster, in das Sie die Befehle aus dieser
Anleitung kopieren.

Container:
Ein abgegrenzter Bereich, in dem ein Teil der Anwendung läuft.

.env-Datei:
Eine nur auf Ihrem Computer gespeicherte Einstellungsdatei mit Passwörtern.
Diese Datei darf niemals auf GitHub hochgeladen oder weitergegeben werden.

localhost:
Eine Bezeichnung für Ihren eigenen Computer.


3. WAS SIE BENÖTIGEN
--------------------

Sie benötigen:

- einen Computer mit Windows 11 (64 Bit),
- ein Windows-Konto mit Administratorrechten,
- eine aktive Internetverbindung für die erste Installation,
- Zugriff auf das GitHub-Repository JohanniterResearch/TRIAS,
- genügend freien Speicher für Docker Desktop und die Container,
- einen aktuellen Browser, zum Beispiel Microsoft Edge, Firefox oder Chrome.


4. SCHNELLSTART FÜR WINDOWS BENUTZER
------------------------------------

- Sicherstellen, dass Docker installiert ist, ansonster Docker unter https://www.docker.com/products/docker-desktop/ herunterladen und installieren.
- Im TRIAS-Github Repository das Repo als Zip herunterladen (Grüner Button "<> Code" -> ZIP Herunterladen.
- Sobald der Download abgeschlossen ist, die ZIP-Datei entpacken.
- Den Entpackten Ordner öffnen und "START_TRIAS.bat" Doppelklicken.
- Beim erstmaligen Ausführen werden die Docker Container erstellt, daher kann es zu einer kurzen Wartezeit kommen. Sobald Task 29/29 erreicht wurde und alle Container healthy/ready anzeigen, ist die Ausführung abgeschlossen.
- Das Browserfenster sollte sich automatisch öffnen -> weiter bei Schritt 13.
- Sollte sich das Browserfenster nicht öffnen, selbst den Browser öffnen und in der Adresszeile "http://localhost:8080" eingeben und die Eingabetaste betätigen. -> weiter bei Schritt 13.


5. VIRTUALISIERUNG UND WSL 2 EINRICHTEN
---------------------------------------

Docker Desktop verwendet unter Windows das "Windows Subsystem for Linux 2",
kurz WSL 2.

1. Öffnen Sie das Startmenü.
2. Suchen Sie nach "PowerShell".
3. Klicken Sie mit der rechten Maustaste auf "Windows PowerShell".
4. Wählen Sie "Als Administrator ausführen".
5. Bestätigen Sie die Sicherheitsabfrage.
6. Kopieren Sie folgenden Befehl in das Fenster und drücken Sie Enter:

   wsl --install

6. Starten Sie Windows neu, wenn Sie dazu aufgefordert werden.

Falls Windows meldet, dass WSL bereits installiert ist, können Sie mit dem
nächsten Abschnitt fortfahren.

Wenn eine Meldung zur deaktivierten Virtualisierung erscheint, muss die
Virtualisierung im BIOS/UEFI des Computers aktiviert werden. Wenden Sie sich
in diesem Fall an Ihre IT-Betreuung oder den Hersteller des Computers.


7. DOCKER DESKTOP INSTALLIEREN
------------------------------

1. Öffnen Sie im Browser:

   https://www.docker.com/products/docker-desktop/

2. Laden Sie Docker Desktop für Windows herunter.
3. Starten Sie die heruntergeladene Installationsdatei.
4. Lassen Sie die Verwendung von WSL 2 aktiviert.
5. Schließen Sie die Installation ab und starten Sie Windows neu, falls dies
   verlangt wird.
6. Öffnen Sie Docker Desktop über das Startmenü.
7. Warten Sie, bis Docker Desktop anzeigt, dass die Docker Engine läuft.

Prüfung:

1. Öffnen Sie eine normale PowerShell.
2. Führen Sie nacheinander diese Befehle aus:

   docker --version
   docker compose version

Beide Befehle müssen eine Versionsnummer anzeigen. Falls "docker wurde nicht
gefunden" erscheint, schließen Sie PowerShell, starten Sie Docker Desktop und
öffnen Sie PowerShell erneut.


8. GIT FÜR WINDOWS INSTALLIEREN
-------------------------------

Git lädt das Projekt von GitHub herunter und kann es später aktualisieren.

1. Öffnen Sie:

   https://git-scm.com/download/win

2. Laden Sie Git für Windows herunter.
3. Starten Sie die Installationsdatei.
4. Übernehmen Sie die vorgeschlagenen Standardeinstellungen.
5. Öffnen Sie danach eine neue PowerShell.
6. Prüfen Sie die Installation:

   git --version

Der Befehl muss eine Versionsnummer anzeigen.


9. PROJEKT VON GITHUB HERUNTERLADEN
-----------------------------------

1. Öffnen Sie eine normale PowerShell.
2. Wechseln Sie in Ihren Dokumente-Ordner:

   cd $HOME\Documents

3. Laden Sie TRIAS herunter:

   git clone https://github.com/JohanniterResearch/TRIAS.git

Da das Repository privat ist, kann sich ein Anmeldefenster von GitHub öffnen.
Melden Sie sich mit dem GitHub-Konto an, das Zugriff auf JohanniterResearch
hat. Ein normales GitHub-Passwort kann nicht direkt in PowerShell als
Git-Passwort verwendet werden; folgen Sie stattdessen dem Browserfenster der
Git-Anmeldung.

4. Wechseln Sie in den neuen Projektordner:

   cd TRIAS

5. Prüfen Sie, ob Sie im richtigen Ordner sind:

   Get-ChildItem

In der Ausgabe müssen unter anderem "Dockerfile", "docker-compose.yml",
"client-app" und "src" stehen.


10. LOKALE EINSTELLUNGSDATEI ERSTELLEN
-------------------------------------

Erstellen Sie aus der sicheren Vorlage eine persönliche .env-Datei:

   Copy-Item .env.example .env

Öffnen Sie die Datei mit dem Windows-Editor:

   notepad .env

Die Datei enthält Zeilen im Format NAME=WERT. Ändern Sie nur den Teil rechts
vom Gleichheitszeichen. Verwenden Sie für Passwörter mindestens 20 Zeichen.
Für diese lokale Einrichtung sind lange Folgen aus Großbuchstaben,
Kleinbuchstaben und Zahlen am einfachsten.

Füllen Sie mindestens diese Werte aus:

DB_PASSWORD=
Passwort für den normalen Datenbankbenutzer.

DB_ROOT_PASSWORD=
Anderes Passwort für die Datenbankverwaltung.

JWT_SECRET=
Eine lange geheime Zeichenfolge mit mindestens 32 Zeichen.

ADMIN_PASSWORD=
Passwort für das lokale Administratorkonto.

TEST_USER_PASSWORD=
Passwort für das lokale Testkonto.

MQTT_PASSWORD=
Passwort für den Nachrichtendienst. Die Entwicklungsumgebung erlaubt lokale
anonyme Verbindungen, der Wert soll trotzdem ausgefüllt werden.

Die bereits eingetragenen Namen wie DB_USER=pls_user, ADMIN_USERNAME=admin
und TEST_USER_USERNAME=user können für den lokalen Start unverändert bleiben.
ALLOWED_ORIGINS= darf für diese lokale Docker-Ausführung leer bleiben.

Zufällige Zeichenfolge erzeugen:

Kopieren Sie die folgenden vier Zeilen gemeinsam in PowerShell. Die letzte
Zeile zeigt eine zufällige Zeichenfolge an, die Sie zum Beispiel als
JWT_SECRET verwenden können.

   $zufall = [System.Security.Cryptography.RandomNumberGenerator]::Create()
   $bytes = New-Object byte[] 48
   $zufall.GetBytes($bytes)
   [Convert]::ToBase64String($bytes)

Wiederholen Sie den Vorgang für weitere Passwörter oder verwenden Sie einen
Passwortmanager. Verwenden Sie nicht dasselbe Passwort für alle Felder.

Speichern Sie die Datei im Editor mit Strg+S und schließen Sie den Editor.

Sicherheitsprüfung:

   git status --short

Die Datei ".env" darf in der Ausgabe nicht erscheinen. Falls sie erscheint,
brechen Sie ab und laden Sie nichts zu GitHub hoch.


11. TRIAS ZUM ERSTEN MAL STARTEN
-------------------------------

Docker Desktop muss geöffnet sein und die Docker Engine muss laufen.

Führen Sie im Projektordner folgenden Befehl aus:

   docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build -d

Was geschieht jetzt?

- Docker lädt beim ersten Mal mehrere Grundpakete aus dem Internet.
- Die Webseite wird gebaut.
- Der Server wird gebaut.
- MySQL und Mosquitto werden gestartet.
- Die Datenbanktabellen werden automatisch angelegt.

Der erste Start kann deutlich länger dauern als spätere Starts. Schließen Sie
PowerShell nicht, solange ein Download oder Build läuft.

Status prüfen:

   docker compose -f docker-compose.yml -f docker-compose.dev.yml ps

Warten Sie, bis "pls-app", "mysql_db" und "mosquitto" laufen beziehungsweise
als "healthy" angezeigt werden. "db-migrate" ist in der Entwicklungsumgebung
nur ein kurzer Hilfscontainer und darf bereits beendet sein.


12. ANWENDUNG IM BROWSER ÖFFNEN
-------------------------------

Öffnen Sie:

http://localhost:8080

Falls die Seite unmittelbar nach dem Start noch nicht lädt, warten Sie
30 Sekunden und aktualisieren Sie die Seite mit Strg+R.


13. ERSTE VERWENDUNG
--------------------

Zuerst wird ein Einsatzort benötigt.

1. Klicken Sie auf "Adminanmeldung".
2. Klicken Sie in der Entwicklungsumgebung auf
   "DEV: Skip to Admin Settings".
3. Klicken Sie im Abschnitt "Einsatzort" auf
   "Einsatzort erstellen/bearbeiten".
4. Klicken Sie auf "Neuen Einsatzort erstellen".
5. Geben Sie einen Namen ein, zum Beispiel "Lokaler Test".
6. Klicken Sie auf "Einsatzort erstellen".
7. Kehren Sie zu den Einstellungen zurück.
8. Klicken Sie auf "Logout".

Anschließend als Einsatzkraft öffnen:

1. Öffnen Sie erneut http://localhost:8080.
2. Klicken Sie auf "DEV: Skip to Role Selection".
3. Wählen Sie den zuvor erstellten Einsatzort.
4. Wählen Sie "Triage" oder "Leitstelle".
5. Klicken Sie auf "Bestätigen".

Die rot umrandeten DEV-Schaltflächen sind nur in der lokalen
Entwicklungsumgebung sichtbar.


14. PROTOKOLLE ANZEIGEN, WENN ETWAS NICHT FUNKTIONIERT
------------------------------------------------------

Status aller Container:

   docker compose -f docker-compose.yml -f docker-compose.dev.yml ps

Letzte Protokollmeldungen:

   docker compose -f docker-compose.yml -f docker-compose.dev.yml logs --tail=200

Protokollmeldungen live verfolgen:

   docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f

Beenden Sie die Live-Anzeige mit Strg+C. Das beendet nur die Anzeige, nicht
die Anwendung.


15. ANWENDUNG STOPPEN UND SPÄTER WIEDER STARTEN
-----------------------------------------------

Container stoppen, Daten behalten:

   docker compose -f docker-compose.yml -f docker-compose.dev.yml stop

Gestoppte Container wieder starten:

   docker compose -f docker-compose.yml -f docker-compose.dev.yml start

Container entfernen, Daten aber behalten:

   docker compose -f docker-compose.yml -f docker-compose.dev.yml down

Nach "down" wieder starten:

   docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d


16. PROJEKT SPÄTER AKTUALISIEREN
--------------------------------

1. Öffnen Sie Docker Desktop.
2. Öffnen Sie PowerShell.
3. Wechseln Sie in den Projektordner:

   cd $HOME\Documents\TRIAS

4. Laden Sie neue Änderungen:

   git pull --ff-only

5. Bauen und starten Sie die aktualisierte Version:

   docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build -d


17. ALLE LOKALEN DATEN LÖSCHEN
------------------------------

ACHTUNG:
Der folgende Befehl löscht die lokale TRIAS-Datenbank vollständig. Angelegte
Einsatzorte, Benutzer, Patienten und Protokolle können danach nicht
wiederhergestellt werden.

Führen Sie diesen Befehl nur aus, wenn Sie wirklich neu beginnen möchten:

   docker compose -f docker-compose.yml -f docker-compose.dev.yml down -v

Danach können Sie eine leere Umgebung neu erstellen:

   docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build -d


18. HÄUFIGE PROBLEME
--------------------

Problem: "docker wurde nicht gefunden"

- Docker Desktop installieren oder starten.
- PowerShell schließen und neu öffnen.
- docker --version erneut ausführen.

Problem: Verbindung mit der Docker Engine nicht möglich

- Docker Desktop öffnen.
- Warten, bis die Engine läuft.
- Falls nötig Docker Desktop neu starten.

Problem: GitHub verweigert den Zugriff

- Prüfen, ob Ihr GitHub-Konto Mitglied oder berechtigter Gast der Organisation
  JohanniterResearch ist.
- Öffnen Sie https://github.com/JohanniterResearch/TRIAS im Browser und prüfen
  Sie, ob Sie das Repository sehen können.
- Wiederholen Sie danach den git-clone-Befehl.

Problem: "no configuration file provided"

- Sie befinden sich im falschen Ordner.
- Wechseln Sie mit cd $HOME\Documents\TRIAS in den Projektordner.

Problem: Port 8080 ist bereits belegt

Prüfen Sie in PowerShell:

   Get-NetTCPConnection -LocalPort 8080 -ErrorAction SilentlyContinue

Beenden Sie die andere Anwendung, die Port 8080 verwendet, oder wenden Sie
sich an Ihre IT-Betreuung.

Problem: Ein Container ist "unhealthy" oder startet immer wieder neu

Zeigen Sie die Protokolle an:

   docker compose -f docker-compose.yml -f docker-compose.dev.yml logs --tail=200

Prüfen Sie besonders:

- Wurden alle Pflichtwerte in .env ausgefüllt?
- Hat JWT_SECRET mindestens 32 Zeichen?
- Läuft Docker Desktop vollständig?
- Sind noch mehrere Gigabyte Speicher frei?

Problem: Die Webseite zeigt nach einer Änderung noch den alten Stand

Neu bauen:

   docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build -d

Danach im Browser Strg+F5 drücken.


19. KURZFASSUNG FÜR JEDEN WEITEREN START
----------------------------------------

1. Docker Desktop öffnen.
2. PowerShell öffnen.
3. Diese Befehle ausführen:

   cd $HOME\Documents\TRIAS
   docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

4. Im Browser öffnen:

   http://localhost:8080

Zum Stoppen:

   docker compose -f docker-compose.yml -f docker-compose.dev.yml stop