ff-handbook/admin/content/2-installation.typ

#import "../../typst/utils.typ": *
#import "@preview/wrap-it:0.1.1": *

= Installation

FF Admin kann über mehrere Wege betrieben werden. Zum einen werden Docker-Images versioniert zur Verfügung gestellt. Weiterhin kann auch das Release Projekt heruntergeladen und verwendet werden.

== Docker

*Disclaimer:* Die Anleitung zum Betrieb von FF Admin mit Docker setzt Kenntnisse mit Docker und Docker-Compose voraus.
\
\
Die Docker-Images können gemeinsam über eine Compose-File konfiguriert und gestartet werden. Auch können die Images einzeln gestartet werden.
\
\
Die Docker-Images sind versioniert. Der `<tag>` des Images kann entweder `latest` für die neueste Version oder `vX.Y.Z` für eine bestimmte Version sein. Die Versionen können auch in den Releases der Repositories der Anwendungen nachgeschlagen werden. Dort lassen sich auch auch Informationen zu neuen Funktionen, Änderungen oder Fehlerbehebungen der jeweiligen Funktion finden.

== Docker-Compose

*App*
#code_file(
  path: "../admin/code/app-compose.yml",
) <app-compose>
Die Verwendung der Werte des Typs Environment werden unter dem Punkt Konfiguration (@config) erklärt.

Die Environment-Variable `SERVERADDRESS` ist optional und kann für eine Abweichende URL des Backends verwendet werden. Ist die Serveradresse nicht angegeben, wird versucht das Backend unter der selben URL mit dem PathPrefix `/api` zu erreichen.
\
\
Eine erweiterte Personalisierung der App mit eigenem Logo der Feuerwehr oder des Vereins ist bei der ersten Einrichtung oder unter dem Modul Einstellungen möglich. Hiervon betroffen ist das Icon im Browser-Tab, jede Anzeige des FF Admin Logos innerhalb der App und das Icon, wenn die WebApp auf einem Gerät installiert wird.
\
\
*Server*
#code_file(
  path: "../admin/code/server-compose.yml",
) <server-compose>

Die Verwendung der Werte des Typs Environment werden unter dem Punkt Konfiguration (@config) erklärt.

Environment Werte können optional sein oder haben Standard-Werte.

Das Fehlen einer geforderten Variable oder die falsche Angabe eines Variablen-Werts verhindert das Starten des der Anwendung.
\
\
Innerhalb dem Ordner, der dem Volume zugeordnet ist, werden Backups und Ausdrucke der geschriebenen Protokolle, Newsletter und alle weiteren Dokumente abgelegt, die hochgeladen oder erstellt werden können.

#pagebreak()

*Datenbank*

Als Datenbank wird Postgres verwendet:
#code_file(
  path: "../admin/code/postgres-compose.yml",
) <postgres-compose>

`POSTGRES_DB` erstellt direkt eine Datenbank, die durch einen angelegten `POSTGRES_USER` verfügbar ist.
\
\
*Hinweis*
Wenn eine Docker-Compose Datei verwendet wird, kann zusätzliche ein Netzwerk angelegt werden.
Dadurch ist das Veröffentlichen der Datenbank-Ports nicht mehr notwendig. Das Entfernern der Port-Exposes verhindert den direkten Zugriff auf die Ports von außerhalb.

Ergänzt muss hierfür das `network` und die Teilhabe des Backend-Containers am Netzwerk:
\
\
1. Ergänzung zu Server und Datenbank:
```
networks:
  - ff_internal
```

2. Ergänzung zur finalen Compose:
```
networks:
  ff_internal:
```

3. Optionale Ergänzung zum Server:
```
depends_on:
  - ff-db
```
Hierdurch kann der Server nicht starten, wenn die verwendete Datenbank nicht läuft.
\
\
Wenn die Datenbank über ein Netzwerk in einer Compose-Datei freigegeben wird, kann als Host der Service-Name der Datenbank angegeben werden. In der angegebenen Datenbank-Konfiguration wäre das `ff-db`.
\
\
Damit die App und der Server aus dem Internet erreichbar sind, kann traefik mit labels verwendet werden.

// === Docker-AIO

// *In Arbeit*

// Ein Docker-Image, welches alle notwendigen Komponenten beinhaltet, ist in der Erstellung.
// \
// \
// Das All-In-One Image abstrahiert das Routing zu App und Server und beinhaltet direkt die Datenbank. Auch werden gleiche Konfigurations-Daten zusammengefasst und an die Container übergeben.

== Git

Eine Alternative zu Docker ist die direkte Ausführung der Anwendungen auf dem Server oder Desktop Gerät.

Hierzu müssen die App und der Server als Quellcode auf das ausführende System geladen und dort direkt verwendet werden. Das System muss NodeJs und die bevorzugte Datenbank installiert haben.
\
\
Für das Hosting von statischen Inhalten wie der App kann Apache oder Nginx verwendet werden. Eine Konfiguration für Nginx ist im Repo der App enthalten.

Die NodeJs Prozesse können auch durch Tools wie pm2 verwaltet werden.

Damit die App und der Server aus dem Internet erreichbar sind, muss das Routing gesondert eingerichtet werden.
\
\
Um die Konfiguration mittels ENV-Variablen an die Anwendungen weitergeben zu können, müssen `.env` Dateien erstellt werden. Hierzu kann die `.env.example` Datei kopiert und die definierten Werte ausgefüllt werden. Nicht benötigte Einträge sollten entfernt werden. 

Die env-Datei im Frontend muss vor dem build-Prozess erstellt sein, da dort die Werte fest in den Code übernommen werden. Weiterhin muss die Datei im Frontend `.env.production` heißen. Die bestehende Datei kann modifiziert werden. Bei einer Änderung muss die App neu gebaut werden. Wird der Server unter der URL der App verwendet, muss in der `.env.production` Datei des Frontends der Wert zum Eintrag von `SERVERADDRESS` auf den leeren String gesetzt werden. 

Die env-Datei im Backend muss vor der Ausführung von `npm run start` angelegt sein. Bei einer Änderung der Einträge muss der Server lediglich neu gestartet werden.
\
\
*App*
```sh
git clone https://forgejo.jk-effects.cloud/Ehrenamt/ff-admin.git
cd ff-admin
npm install
npm run build
```
Der mit `npm run build` erstellte dist Ordner kann mit Apache oder Nginx zur veröffentlicht werden.
\
\
*Server*
```sh
git clone https://forgejo.jk-effects.cloud/Ehrenamt/ff-admin-server.git
cd ff-admin-server
npm install
npm run build
npm run start
```

== Konfiguration <config>

Folgende Werte können zu einem Container konfiguriert werden:

#table(
  columns: (35%, 1fr, 10%, auto),
  inset: 5pt,
  table.header(
    [*Variable*], [*Zweck*], [*Fallback*], [*optional*]
  ),
  align: (x, y) => (
    if x == 3 { center }
    else { left }
  ),
  table.cell(colspan: 4)[⬇️ App-Variablen],
  "SERVERADDRESS", "URL, über welche das Backend erreicht werden kann. Die URL muss mit http:// oder https:// starten und sollte keinen Pfad beinhalten. Die App versucht das Backend unter <SERVERADDRESS>/api zu erreichen. Laufen Backend und App auf der gleichen URL, kann diese Variable weggelassen werden.", "", "✅",
  "", "", "", "",
  table.cell(colspan: 4)[⬇️ Server-Variablen],
  "DB_HOST", "URL zur Datenbank", "", "💥",
  "DB_PORT", "Port der Datenbank", "5432", "✅",
  "DB_NAME", "Name der Datenbank", "", "💥",
  "DB_USERNAME", "Nutzername für Zugang zu Datenbank", "", "💥",
  "DB_PASSWORD", "Passwort zum Zugang zur Datenbank", "", "💥",
  "APPLICATION_SECRET", "Zufällige Zeichenkette zur Validierung der Session-Tokens.", "", "💥",
  "USE_SECURITY_STRICT_LIMIT","Soll ein Anfrage-Limit für Login, Reset und Co gesetzt werden? \nIn diesem Fall ist der Nutzer nicht angemeldet, sondern versucht es.","true","✅",
  "SECURITY_STRICT_LIMIT _WINDOW","Über welches Zeitfenster soll das Limit angewandt werden? \nFormat: [0-9]*(y|d|h|m|s)","15m","✅",
  "SECURITY_STRICT_LIMIT _REQUEST_COUNT","Wie viele fehlerhafte Anfragen müssen gesendet werden, bis das Limit aktiviert ist?","15","✅",
  "USE_SECURITY_LIMIT","Soll ein Anfrage-Limit für Anfragen innerhalb der App gesetzt werden? \nIn diesem Fall ist der Nutzer angemeldet.","true","✅",
  "SECURITY_LIMIT_WINDOW","Über welches Zeitfenster soll das Limit angewandt werden? \nFormat: [0-9]*(y|d|h|m|s)","1m","✅",
  "SECURITY_LIMIT_REQUEST _COUNT","Wie viele fehlerhafte Anfragen müssen gesendet werden, bis das Limit aktiviert ist?","500","✅",
  "TRUST_PROXY",[
    Wird der Server hinter einem Proxy betrieben und Rate-Limit verwendet?
    Ist dieser Wert nicht gesetzt, wird davon ausgegangen, dass kein Proxy verwendet wird.
    \
    \
    Folgende Werte können gesetzt werden:\
    true / false\
    Anzahl der Proxies: [0-9]\*\
    IP-Adresse des Proxy: ip\
    IP-Adressen der Proxy: ip1,ip2,...
  ],"","✅",
  "", "", "", "",
  table.cell(colspan: 4)[⬇️ Database-Variablen],
  "POSTGRES_DB", "Name der Datenbank, die bei Erstellung direkt angelegt wird.", "", "💥",
  "POSTGRES_USER", "Benutzername des Users, der bei Erstellung direkt angelegt wird.", "", "💥",
  "POSTGRES_PASSWORD", "Passwort zum User, das bei Erstellung gesetzt wird.", "", "💥",
)

💥: Ein Fehlen dieser Variable verhindert das Starten der Anwendung!
\
\
*Hinweis:* Eine fehlerhafte Konfiguration der optionalen oder geforderten Variable verhindert das Starten der Anwendung.

*Hinweis:* Ist eine Datenbank leer, werden Backups automatisch wiederhergestellt, sollte ein solches existieren.

#pagebreak()

== Update der Version

Um eine Version auf eine Neuere zu aktualisieren, muss meist nur der Docker-Tag oder das Repo ersetzt werden.

Wer Docker mit `latest` nutzt, kann das neue Image direkt mit `docker pull` neu beziehen und dann den Container neustarten. 
\
\
Informationen zu neuen Versionen können innerhalb der App unter `Benutzer > Version` oder in den Release-Pages gefunden werden.

Die Releases beinhalten Informationen zu einem Update und was zu beachten ist. So enthalten die Release-Informationen beispielsweise Vorbereitungen vor einem Update.
\
\
Bei Verwendung mittels Git, müssen die Repos neu bezogen werden. Anschließend müssen die Dependencies neu installiert und die Anwendungen neu gebaut werden.

== Wechsel des Datenbanksystems

Eine Funktion, die mit den Backups eingeführt wurde, ist `AUTO RESTORE`. `AUTO RESTORE` ermöglicht die automatische Wiederherstellung des letzten Backups - sofern vorhanden - wenn die Datenbank beim Start des Servers leer ist. 

Dies vereinfacht auch den Wechsel zwischen Datenbanken, da nur eine neue Verbindung zu einer anderen Datenbank aufgebaut werden muss und die Daten nach dem Neustart des Servers automatisch in die neue leere Datenbank übertragen werden.

== WebApp

FF Admin ist als WebApp verfügbar. Dadurch lässt sich die Anwendung auf einem Smartphone oder Desktop über den Browser installieren.

#pagebreak()

== Einrichtung

Um die Anwendung nutzen zu können, kann ein erster Administrator-Account wie folgt erstellt werden:

#wrap-content(
  figure(
    image("../images/setup_step1.png", width: 5cm),
  ),
  align: right
)[
*Admin Benutzer erstellen*: Um einen ersten Benutzer mit Administrator-Berechtigungen zu erstellen, muss der Einrichtungs-Assistent unter dem Pfad `/setup` aufgerufen werden. Nach der initialen Einrichtung wird der Pfad automatisch geblockt.

Der Einrichtungs-Assistent ermöglicht das Setzen erster Einstellungen wie Vereinsdaten und Logos. Auch ermöglicht der Assistent das Einrichten der Mail-Adresse, die von FF-Admin verwendet werden soll. Über diese Mailadresse können andere Nutzer eingeladen, Zugänge zurückgesetzt oder Newsletter versendet werden.
]

#grid(
  columns: (1fr, 1fr, 1fr),
  align: center,
  figure(
    image("../images/setup_step2.png", width: 5cm),
  ),
  figure(
    image("../images/setup_step4.png", width: 5cm),
  ),
  figure(
    image("../images/setup_step5.png", width: 5cm),
  )
)

*Rollen und Berechtigungen*: Unter `Verwaltung > Rollen` können die Rollen und Berechtigungen für die Benutzer erstellt und angepasst werden.

*Nutzer einladen*: Unter `Verwaltung > Benutzer` können weitere Nutzer eingeladen werden. Diese erhalten dann eine E-Mail mit einem Link. Über diesen Link können die Nutzer einen Account mit Zugangsdaten erstellen. Für den Zugang können entweder TOTP oder Passwörter verwendet werden.