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

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

= Installation

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

*Webseite*
#code_file(
  path: "../webpage/code/frontend-compose.yml",
) <website-compose>
Die Verwendung der Werte des Typs Environment werden unter dem Punkt Konfiguration erklärt.
\
\
Das Volume dient zur erweiterten Personalisierung der Webseite mit eigenem Logo der Feuerwehr oder des Vereins. Hiervon betroffen ist nur Icon im Browser-Tab.
\
\
Die Konfiguration der Volumes ist optional, falls Sie die Standard-Logos verwenden wollen.

Die Dateien müssen exakt gleich geschrieben sein. Achten Sie deshalb auf Schreibfehler und Groß-/Kleinschreibung.
\
\
*CMS - Inhaltsverwaltung*
#code_file(
  path: "../webpage/code/strapi-compose.yml",
) <strapi-compose>

Die Verwendung der Werte des Typs Environment werden unter dem Punkt Konfiguration 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 Uploads abgelegt.

#pagebreak()

*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: "../webpage/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: "../webpage/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.
\
\
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-Dateien müssen vor der Ausführung von `npm run start` angelegt sein. Bei einer Änderung der Einträge müssen die Anwendungen lediglich neu gestartet werden.
\
\
*Webseite*
```sh
git clone https://forgejo.jk-effects.cloud/Ehrenamt/ff-webpage.git
cd ff-webpage
npm install
npm run build
npm run start
```
`npm run start` nutzt das eingebaute Hosting von Nuxt, welches SSR ermöglicht, um die App zu betreiben.
\
\
*Strapi*
```sh
git clone https://forgejo.jk-effects.cloud/Ehrenamt/ff-webpage-cms.git
cd ff-webpage-cms
npm install
npm run build
npm run start
```

== Konfiguration

Folgende Werte können zu einem Container konfiguriert werden:

#table(
  columns: (auto, 1fr, 15%, auto),
  inset: 5pt,
  table.header(
    [*Variable*], [*Zweck*], [*Fallback*], [*optional*]
  ),
  align: (x, y) => (
    if x == 3 { center }
    else { left }
  ),
  table.cell(colspan: 4)[⬇️ App-Variablen],
  "NUXT_STRAPI_URL", "URL, unter der das CMS erreichbar ist.", "", "💥",
  "NUXT_PUBLIC_STRAPI_URL","URL, unter der das CMS erreichbar ist.", "", "💥",
  "NUXT_PUBLIC_APP_TITLE", "Text im Browser-Tab", "FF Webpage", "✅",
  "", "", "", "",
  table.cell(colspan: 4)[⬇️ Server-Variablen],
  "DB_TYPE", "Folgende Datenbanktypen sind verfügbar: mysql, postgres", "", "💥",
  "DB_HOST", "URL zur Datenbank", "", "💥",
  "DB_PORT", "Port der Datenbank", "", "💥",
  "DB_NAME", "Name der Datenbank in welcher die Tabellen erstellt werden.", "", "💥",
  "DB_USERNAME", "Nutzername für Zugang zu Datenbank", "", "💥",
  "DB_PASSWORD", "Passwort zum Zugang zur Datenbank", "", "💥",
  "JWT_SECRET", "", "", "💥",
  "ADMIN_JWT_SECRET", "", "", "✅",
  "APP_KEYS", "", "", "✅",
  "API_TOKEN_SALT", "", "", "✅",
  "TRANSFER_TOKEN_SALT", "", "", "✅",
  "", "", "", "",
  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.

*Hinweis:* Eine Änderung der Datenbank übernimmt nicht automatisch die Daten in die neue Datenbank.

== 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 im Account des Eigentümers 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.