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

#import "../../typst/utils.typ": *

= Installation

FF Operation 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 Operation 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

*Datenbank*

Als Datenbank können MySQL, Postgres und SQLite verwendet werden. Postgres wird für den Produktiven Einsatz empfohlen.
\
\
Konfiguration von MySQL:
#code_file(
  path: "../operation/code/mysql-compose.yml",
) <mysql-compose>

`MYSQL_USER` und `MYSQL_PASSWORD` sind optional. Werden diese nicht gesetzt, kann der Server entweder mit dem Nutzer `root` und dem gesetzten `MYSQL_ROOT_PASSWORD` Zugang zur Datenbank erhalten, oder es wird im nachhinein ein Nutzerzugang erstellt, der Zugriff auf die erstellte Datenbank hat.

`MYSQL_DATABASE` erstellt direkt eine Datenbank, die durch einen angelegten `MYSQL_USER` verfügbar ist.
\
\
Konfiguration von Postgres:
#code_file(
  path: "../operation/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-Port-Exposes 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.

== 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 aud das System geladen und dort direkt verwendet werden.
\
\
Die Veröffentlichung der App und des Servers, damit diese aus dem Internet erreichbar sind muss gesondert eingerichtet werden.
\
\
Das System muss NodeJs und die bevorzugte Datenbank installiert haben.
\
\
Für das Hosting von statischen Inhalten 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.
\
\
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.

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-operation.git
cd ff-operation
npm install
npm run build
```
Der durch `npm run build` erstellte dist Ordner kann mit Apache oder Nginx zur Verfügung gestellt werden.
\
\
*Server*
```sh
git clone https://forgejo.jk-effects.cloud/Ehrenamt/ff-operation-server.git
cd ff-operation-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)[⬇️ Database-Variablen],
  "MYSQL_DATABASE", "Name der Datenbank, die bei Erstellung direkt angelegt wird.", "", "💥",
  "MYSQL_USER", "Benutzername des Users, der bei Erstellung direkt angelegt wird.", "", "✅",
  "MYSQL_PASSWORD", "Passwort zum User, das bei Erstellung gesetzt wird.", "", "✅",
  "MYSQL_ROOT_PASSWORD", "Passwort für den User root, das bei Erstellung gesetzt wird.", "", "💥",
  "", "", "", "",
  "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!
🚨: Bei Verwendung von SQLite sind diese Variablen nicht notwendig!
\
\
*Hinweis:* Eine fehlerhafte Konfiguration der optionalen oder geforderten Variable verhindert das Starten der Anwendung.

== 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

`AUTO RESTORE` ist standardmäßig aktiviert und 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 Operation ist als WebApp verfügbar. Dadurch lässt sich die Anwendung auf einem Smartphone oder Desktop über den Browser installieren.