operation docker installation

2025-02-16 14:10:55 +01:00 · 2025-02-16 14:10:55 +01:00 · d162f2f0fa
commit d162f2f0fa
parent 7646a1a96f
7 changed files with 162 additions and 2 deletions
--- a/admin/code/server-compose.yml
+++ b/admin/code/server-compose.yml
@ -1,6 +1,6 @@
 ff-admin-server:
  image: docker.registry.jk-effects.cloud/ehrenamt/ff-admin/server:<version>
-  container_name: ff_member_administration_server
+  container_name: ff_admin_server
  restart: unless-stopped
  ports:
    - "5000:5000"
--- a/admin/content/2-installation.typ
+++ b/admin/content/2-installation.typ
@ -238,6 +238,7 @@ Folgende Werte können zu einem Container konfiguriert werden:
 )

 💥: Ein Fehlen dieser Variable verhindert das Starten der Anwendung!
+
 🚨: Bei Verwendung von SQLite sind diese Variablen nicht notwendig!
 \
 \
--- a/ff-operation.pdf
+++ b/ff-operation.pdf
--- a/operation/code/app-compose.yml
+++ b/operation/code/app-compose.yml
@ -0,0 +1,16 @@
+ff-operation-app:
+  image: docker.registry.jk-effects.cloud/ehrenamt/ff-operation/app:<version>
+  container_name: ff_operation
+  restart: unless-stopped
+  ports:
+    - "80:80"
+  environment:
+    - SERVERADDRESS=<backend_url>
+    - APPNAMEOVERWRITE=<appname>
+    - IMPRINTLINK=<imprint link>
+    - PRIVACYLINK=<privacy link>
+    - CUSTOMLOGINMESSAGE=<betrieben von xy>
+  volumes:
+    - <volume|local path>/favicon.ico:/usr/share/nginx/html/favicon.ico
+    - <volume|local path>/favicon.png:/usr/share/nginx/html/favicon.png
+    - <volume|local path>/Logo.png:/usr/share/nginx/html/Logo.png
--- a/operation/code/server-compose.yml
+++ b/operation/code/server-compose.yml
@ -0,0 +1,36 @@
+ff-operation-server:
+  image: docker.registry.jk-effects.cloud/ehrenamt/ff-operation/server:<version>
+  container_name: ff_operation_server
+  restart: unless-stopped
+  ports:
+    - "5000:5000"
+  environment:
+    - DB_TYPE=<database type>
+    - DB_HOST=<database host>
+    - DB_PORT=<database port>
+    - DB_NAME=<database name>
+    - DB_USERNAME=<database username>
+    - DB_PASSWORD=<database password>
+    - JWT_SECRET=<jwt secret>
+    - JWT_EXPIRATION=<jwt expiration>
+    - REFRESH_EXPIRATION=<refresh expiration>
+    - PWA_REFRESH_EXPIRATION=<pwa refresh expiration>
+    - MAIL_USERNAME=<mailadress|username>
+    - MAIL_PASSWORD=<mail password>
+    - MAIL_HOST=<mail server url>
+    - MAIL_PORT=<port>
+    - MAIL_SECURE=<boolean>
+    - CLUB_NAME=<club name>
+    - CLUB_WEBSITE=<club website>
+    - BACKUP_INTERVAL=<backup interval>
+    - BACKUP_COPIES=<backup parallel copies>
+    - BACKUP_AUTO_RESTORE=<boolean>
+    - USE_SECURITY_STRICT_LIMIT=<boolean>
+    - SECURITY_STRICT_LIMIT_WINDOW=<time window>
+    - SECURITY_STRICT_LIMIT_REQUEST_COUNT=<strict_request_count>
+    - USE_SECURITY_LIMIT=<boolean>
+    - SECURITY_LIMIT_WINDOW=<time window>
+    - SECURITY_LIMIT_REQUEST_COUNT=<request_count>
+    - TRUST_PROXY=<proxy config>
+  volumes:
+    - <volume|local path>:/app/files
--- a/operation/content/2-installation.typ
+++ b/operation/content/2-installation.typ
@ -16,6 +16,53 @@ Die Docker-Images sind versioniert. Der `<tag>` des Images kann entweder `latest

 == Docker-Compose

+*App*
+#code_file(
+  path: "../operation/code/app-compose.yml",
+) <app-compose>
+Die Verwendung der Werte des Typs Environment werden unter dem Punkt Konfiguration (@config) erklärt.
+
+Alle Environment Werte sind Optional und haben Standard-Werte.
+
+Ist ein Wert optional und hat keinen Fallback, so wird in der Anwendung nichts angezeigt.
+\
+\
+Die Volumes dienen zur erweiterten Personalisierung der App mit eigenem Logo der Feuerwehr oder des Vereins. Hiervon betroffen ist das Icon im Browser-Tab, jede Anzeige des FF Operation Logos innerhalb der App und das Icon, wenn die WebApp auf einem Gerät installiert wird.
+\
+\
+Die Konfiguration der Volumes ist optional, falls Sie die Standard-Logos verwenden wollen.
+\
+\
+Ein Teil der Logos haben eine Anforderung an die Auflösung:
+#table(
+  columns: (1fr, 1fr, 1fr),
+  inset: 5pt,
+  table.header(
+    [*Icon*], [*Auflösung*], [*Anzeigeort*]
+  ),
+  "favicon.ico", "48x48 px", "Browser-Tab Icon",
+  "favicon.png", "512x512 px", "WebApp Icon zur Installation",
+  "Logo.png", "beliebig", "Innerhalb der Anwendung",
+)
+Die Dateien müssen exakt gleich geschrieben sein. Achten Sie deshalb auf Schreibfehler und Groß-/Kleinschreibung.
+
+#pagebreak()
+
+*Server*
+#code_file(
+  path: "../operation/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 und Newsletter abgelegt.
+\
+\
 *Datenbank*

 Als Datenbank können MySQL, Postgres und SQLite verwendet werden. Postgres wird für den Produktiven Einsatz empfohlen.
@ -114,7 +161,7 @@ npm run start
 Folgende Werte können zu einem Container konfiguriert werden:

 #table(
-  columns: (35%, 1fr, 10%, auto),
+  columns: (35%, 1fr, 13%, auto),
  inset: 5pt,
  table.header(
    [*Variable*], [*Zweck*], [*Fallback*], [*optional*]
@ -123,6 +170,52 @@ Folgende Werte können zu einem Container konfiguriert werden:
    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 darf keinen Pfad beinhalten. Wenn das Backend auf der gleichen URL wie die App läuft, kann diese Variable weggelassen werden.", "", "✅",
+  "APPNAMEOVERWRITE", "Anzeige eines anderen Namens als FF Operation.", "FF Operation", "✅",
+  "IMPRINTLINK", "Link zum Impressum des Betreibers.", "", "✅",
+  "PRIVACYLINK", "Link zur Datenschutzerklärung des Betreibers.", "", "✅",
+  "CUSTOMLOGINMESSAGE", "Nachricht auf der Login-Seite.\n(Bsp.: betrieben von xy)", "", "✅",
+  "", "", "", "",
+  table.cell(colspan: 4)[⬇️ Server-Variablen],
+  "DB_TYPE", "Folgende Datenbanktypen sind verfügbar: mysql, sqlite, postgres", "mysql", "✅",
+  "DB_HOST", "URL zur Datenbank oder Dateipfad zur SQLite-Datenbank", "", "💥",
+  "DB_PORT", "Port der Datenbank", "3306", "🚨",
+  "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", "Zufällige Zeichenkette zur Validierung der Session-Tokens.", "", "💥",
+  "JWT_EXPIRATION", "Gültigkeitsdauer eines Session-Tokens.\nFormat: [0-9]*(y|d|h|m|s)", "15m", "✅",
+  "REFRESH_EXPIRATION", "Gültigkeitsdauer eines Logins nach letzter Nutzung der App im Browser \nFormat: [0-9]*(y|d|h|m|s)", "1d", "✅",
+  "PWA_REFRESH_EXPIRATION", "Gültigkeitsdauer eines Logins nach letzter Nutzung der installierten App\nFormat: [0-9]*(y|d|h|m|s)", "5d", "✅",
+  "MAIL_USERNAME", "Nutzername oder Mailadresse", "", "💥",
+  "MAIL_PASSWORD", "Passwort zum Nutzernamen oder der Mailadresse", "", "💥",
+  "MAIL_HOST", "URL des Mailservers", "", "💥",
+  "MAIL_PORT", "Port des Mailservers für Versand (SMTP).\nPorts sind 25, 465, 587", "587", "✅",
+  "MAIL_SECURE", "Soll eine Secure Verbindung aufgebaut werden. Muss true sein bei Port 465.", "false", "✅",
+  "CLUB_NAME", "Wird für TOTP Titel verwendet.", "FF Operation", "✅",
+  "CLUB_WEBSITE", "", "", "✅",
+  "BACKUP_INTERVAL", "Wie viele Tage Abstand sollen zwischen Backups liegen? (min. 1)", "1", "✅",
+  "BACKUP_COPIES", "Wie viele parallele Kopien von Backups sollen parallel Verfügbar sein? (min. 1)", "7", "✅",
+  "BACKUP_AUTO_RESTORE", "Soll das neueste Backup bei Server-Start automatisch geladen werden, wenn die Datenbank als leer erkannt wird?", "true", "✅",
+  "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],
  "MYSQL_DATABASE", "Name der Datenbank, die bei Erstellung direkt angelegt wird.", "", "💥",
  "MYSQL_USER", "Benutzername des Users, der bei Erstellung direkt angelegt wird.", "", "✅",
@ -135,11 +228,14 @@ Folgende Werte können zu einem Container konfiguriert werden:
 )

 💥: 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 die Daten nur automatisch in die neue Datenbank, wenn `BACKUP_AUTO_RESTORE` aktiviert ist und ein Backup angelegt ist. Es werden dann die Daten des gefundenen Backups in die neue Datenbank eingefügt.
+
 == Update der Version

 Um eine Version auf eine Neuere zu aktualisieren, muss meist nur der Docker-Tag oder das Repo ersetzt werden.
@ -163,3 +259,13 @@ Dies vereinfacht auch den Wechsel zwischen Datenbanken, da nur eine neue Verbind
 == WebApp

 FF Operation ist als WebApp verfügbar. Dadurch lässt sich die Anwendung auf einem Smartphone oder Desktop über den Browser installieren.
+
+== Einrichtung
+
+Um die Anwendung nutzen zu können, kann ein erster Administrator-Account wie folgt erstellt werden:
+
+1. *Admin Benutzer erstellen*: Erstellen Sie einen Admin Benutzer unter dem Pfad /setup, um auf die Mitgliederverwaltung Zugriff zu erhalten. Nach der Erstellung des ersten Benutzers wird der Pfad automatisch geblockt.
+
+2. *Rollen und Berechtigungen*: Unter `Benutzer > Rollen` können die Rollen und Berechtigungen für die Benutzer erstellt und angepasst werden.
+
+3. *Nutzer einladen*: Unter `Benutzer > Benutzer` können weitere Nutzer eingeladen werden. Diese erhalten dann eine E-Mail mit einem Link, um ein TOTP zu erhalten.
--- a/webpage/content/2-installation.typ
+++ b/webpage/content/2-installation.typ
@ -178,6 +178,7 @@ Folgende Werte können zu einem Container konfiguriert werden:
 )

 💥: Ein Fehlen dieser Variable verhindert das Starten der Anwendung!
+
 🚨: Bei Verwendung von SQLite sind diese Variablen nicht notwendig!
 \
 \