Deployment

In diesem Abschnitt wird beschrieben, wie GENTRAIN sowohl intern als auch von externen Organisationen (z. B. Forschungsinstitute oder Gesundheitsbehörden) bereitgestellt werden kann. Er erläutert den Bereitstellungs-Workflow, die Umgebungsvariablen, Secrets und die Automatisierung mittels GitHub Actions.

🏗️ 1. Überblick über den Deployment-Prozess

GENTRAIN unterstützt zwei Hauptmodi für die Bereitstellung:

Modus	Anwendungsfall	Tooling
Development	Lokales Testen oder Anpassen	`docker-compose.dev.yaml`
Production	Stabile Instanz für Organisationen	`docker-compose.prod.yaml` + Caddy

Das Repository enthält Beispiele und Vorlagen zur Unterstützung der Einrichtung:

.env.example — zeigt erforderliche und optionale Umgebungsvariablen.
Caddyfile.example — Beispielkonfiguration für den Reverse Proxy Caddy, einschließlich TLS und Routing zur API und zum Frontend.
.github/workflows/prod_deployment.yml — Produktionsworkflow (GitHub Actions CI/CD), der in der Hauptbereitstellung verwendet wird und an eigene Server angepasst werden kann.

⚙️ 2. Voraussetzungen

Folgende Abhängigkeiten müssen vor der Bereitstellung installiert sein:

Docker (≥ 20.x)
Docker Compose (plugin ≥ v2)
Git

🧩 3. Lokale Entwicklungsumgebung

Führe GENTRAIN lokal aus. Im Abschnitt Getting Started finden Sie eine ausführliche Anleitung.

# Start Redis, Postgres, and API
docker compose -f docker-compose.dev.yaml up -d

# Start Frontend, Admin, and Docs (in separate terminals)
npm run dev

Alternativ können Sie das bereitgestellte Skript verwenden:

sh dev.sh

🚀 4. Produktionsbereitstellung

Die Produktionsbereitstellung nutzt Caddy als Reverse Proxy mit HTTPS-Unterstützung. Permanente Docker-Volumes speichern Datenbanken, Uploads und gebaute statische Dateien.

Schritt 1 — Repository klonen

git clone https://github.com/DiltheyLab/GENTRAIN.git
cd GENTRAIN

Schritt 2 — Umgebungsvariablen konfigurieren

Wenn Sie keinen Workflow für das Deployment verwenden, legen Sie die Variablen, die in dem Abschnitt Erklärung der Variablen und Secrets beschrieben sind, manuell an:

cp .env.example .env

Bearbeiten Sie die .env mit den richtigen Hostnamen, Secrets und Pfaden.

Schritt 3 — Caddy konfigurieren

Verwenden Sie Caddyfile.example als Vorlage für die HTTPS- und Routing-Konfiguration:

Frontend wird unter der Hauptdomaine bereitgestellt
Für die API, die Dokumentation und das Admin-Panel werden entsprechende Subdomains definiert und geroutet.
Automatische TLS-Zertifikate über Let’s Encrypt werden unterstützt

Schritt 4 — Redis konfigurieren

Verwenden Sie /backend/redis/redis.conf.prod.example als Vorlage für die Konfiguration:

cp /backend/redis/redis.conf.prod.example /backend/redis/redis.conf.prod

Anschließend müssen Sie lediglich ein Password für den default-User setzen. Die anzupassenden Stellen sind in der Beispiel-Konfigurationsdatei mit insert_password_for_default_user markiert. Beachten Sie dass auch innerhalb der übergreifenden .env-Datei ein entsprechender Eintrag gesetzt sein muss um eine Redis-Verbindung herzustellen (REDIS_PASSWORD).

Schritt 5 — Stack starten

docker compose -f docker-compose.prod.yaml up -d --build

⚙️ 5. Automatisierte Bereitstellung mit GitHub Actions

Das Repository enthält einen Produktions-Workflow unter .github/workflows/prod_deployment.yml.

Dieser Workflow automatisiert:

Das Bauen von Frontend und Dokumentation
Die SSH-Verbindung zum Produktionsserver
Das Erzeugen der .env-Datei aus GitHub Variablen und Secrets
Erstellung eines Datenbank-Backups (es werden nur die letzten 5 Datenbank-Backups gespeichert)
Das sichere Neustarten der Docker-Container
Slack-Benachrichtigungen bei Erfolg oder Fehler

::: Datenbank-Backup

Das erstellte Datenbank-Backup kann wiefolgt angewendet werden:

docker exec -i gentrain-db psql -U gentrain -d test < db_dumps/<db_dump>.sql

Es kann jederzeit ein manuelles Datenbank-Backup erstellt werden:

docker exec -t gentrain-db pg_dump -d gentrain -U gentrain > db_dumps/`date +%Y-%m-%d"_"%H_%M_%S`.sql

:::

Organisationen können denselben Workflow nutzen, indem sie:

Das Repository forken oder privat spiegeln
Eigene GitHub Actions Variablen und Secrets hinzufügen
Einen Branch prod für Produktionsupdates definieren

🔧 6. Erklärung der Variablen und Secrets

Der Workflow generiert die .env-Datei dynamisch auf dem Server anhand von GitHub Variablen (vars) und Secrets (secrets).

Im Folgenden werden alle wichtigen Parameter erläutert.

🔹 Allgemein / Verbindung

Name	Typ	Beschreibung
`SSH_HOST`	Variable	Hostname oder IP des Produktionsservers (verwendet von `appleboy/ssh-action`).
`SSH_USER`	Variable	Benutzername für die SSH-Verbindung (z. B. `ubuntu`, `gentrain`).
`SSH_PRIVATE_KEY`	Secret	Privater SSH-Schlüssel zur Authentifizierung (niemals ins Repo committen).
`GENTRAIN_DIR`	Variable	Pfad auf dem Server, in dem GENTRAIN installiert ist (z. B. `/opt/gentrain`).
`PRODUCTION_BRANCH`	Variable	Git-Branch, der für die Produktion verwendet wird (z. B. `prod`).
`GENTRAIN_PASSWORD`	Secret	Sudo-Passwort auf dem Server, um Docker mit Root-Rechten neu zu starten.

🔹 Anwendung / API-Konfiguration

Name	Typ	Beschreibung
`VITE_API_HOST`	Variable	Öffentlicher API-Endpunkt (z. B. `https://api.deinedomain.org`). Wird im Frontend-Build verwendet.
`VITE_APP_URL`	Variable	Basis-URL der Anwendung (für Weiterleitungen und Links).
`APP_ENV` or `PROD_APP_ENV`	Variable	Legt die Laufzeitumgebung fest (z. B. `production`).
`API_DATA_DIRECTORY`	Variable	Pfad, in dem die API Dateien und Pathogen-Daten speichert.

🔹 Datenbank und Redis

Name	Typ	Beschreibung
`DATABASE_DRIVER`	Variable	Datenbanktreiber (in der Regel `postgres`).
`DATABASE_HOST`	Variable	Hostname des PostgreSQL-Dienstes (Containername oder externer Host).
`DATABASE_PORT`	Variable	Port des PostgreSQL-Dienstes (Standard: `5432`).
`DATABASE_NAME`	Variable	Name der GENTRAIN-Datenbank.
`DATABASE_USER`	Variable	Benutzername für den Datenbankzugriff.
`DATABASE_PASSWORD`	Secret	Passwort für die Datenbankauthentifizierung.
`REDIS_HOST`	Variable	Hostname des Redis-Dienstes.
`REDIS_PORT`	Variable	Port des Redis-Dienstes (Standard: `6379`).
`REDIS_USERNAME`	Variable	Optionaler Redis-Benutzername.
`REDIS_PASSWORD`	Secret	Passwort für die Redis-Authentifizierung (falls aktiviert).

🔹 Admin-Panel

Name	Typ	Beschreibung
`ADMIN_PANEL_PORT`	Variable	Port, auf dem das Admin-Interface läuft (z. B. `5540`).
`ADMIN_PANEL_URL`	Variable	Öffentliche oder interne URL für den Admin-Zugang.
`DEFAULT_ADMIN_USERNAME`	Variable	Standard-Admin-Benutzername (bei der ersten Einrichtung).
`DEFAULT_ADMIN_PASSWORD`	Secret	Standard-Admin-Passwort (sollte nach dem ersten Login geändert werden).

🔹Sicherheit und Sitzungen

Name	Typ	Beschreibung
`SESSION_SECRET`	Secret	Wird zur Verschlüsselung von Sitzungen genutzt.
`COOKIE_SECRET`	Secret	Wird zum Signieren sicherer Cookies verwendet.

🔹 Benachrichtigungen

Name	Typ	Beschreibung
`SLACK_WEBHOOK_URL`	Variable	Webhook-URL für Slack-Benachrichtigungen über den Status der Bereitstellung.

🧱 7. Beispiel: Generierung der `.env` im Workflow

Während des GitHub Actions-Laufs werden die Umgebungsvariablen per SSH gesetzt:

- name: Generate environment variables
  uses: appleboy/ssh-action@v1.0.3
  with:
    host: ${{ vars.SSH_HOST }}
    username: ${{ vars.SSH_USER }}
    key: ${{ secrets.SSH_PRIVATE_KEY }}
    script: |
      cd ${{ vars.GENTRAIN_DIR }}
      rm -f .env
      touch .env
      echo -e "VITE_API_HOST=${{vars.VITE_API_HOST}}" >> .env
      ...

So wird sichergestellt, dass die .env-Datei auf dem Server immer den aktuellen GitHub-Variablen entspricht.

💾 8. Persistente Volumes

Im Produktions-Compose sind benannte Docker-Volumes definiert:

Volume	Beschreibung
`postgres_data`	PostgreSQL-Datenbankdaten (sollte gesichert werden).
`api_data`	Pathogen-Schemata, Beispieldatensätze
`frontend_files`, `docs_files`	Gebaute Frontend- und Dokumentationsdateien.
`caddy_config`, `caddy_data`	Caddy-Konfiguration, Zertifikate und Logs.

Backup-Beispiel:

docker exec -t gentrain-db pg_dumpall -c -U ${DATABASE_USER} > backup.sql
cp -r ./api_data ./backup_api_data_$(date +%F)

🧯 9. Rollback

Falls eine Bereitstellung fehlschlägt:

docker compose -f docker-compose.prod.yaml down
git checkout <previous-tag>
docker compose -f docker-compose.prod.yaml up -d --build

Datenbank wiederherstellen (falls erforderlich):

psql -U $DATABASE_USER -d $DATABASE_NAME -f backup.sql

🧠 10. Sicherheitsrichtlinien

Secrets in GitHub regelmäßig rotieren
SSH-Zugriff auf vertrauenswürdige IPs beschränken
HTTPS mit automatischer Erneuerung über Caddy verwenden
Keine Klartext-Passwörter in .env-Dateien speichern
Admin-Panel bei öffentlichem Zugriff mit Basic Auth absichern

📁 11. Wichtige Dateien im Repository

Datei	Zweck
`.env.example`	Beispielkonfiguration für benötigte Umgebungsvariablen
`Caddyfile.example`	Beispielkonfiguration für HTTPS-Reverse-Proxy
`docker-compose.dev.yaml`	Entwicklungsumgebung
`docker-compose.prod.yaml`	Produktionsumgebung
`.github/workflows/prod_deployment.yml`	Produktions-CI/CD-Workflow
`.github/workflows/dev_deployment.yml`	Entwicklungs-CI/CD-Workflow
`init-entrypoint.sh`	Initialisiert Volumes und Benutzerrechte für Produktionscontainer

🏗️ 1. Überblick über den Deployment-Prozess​

⚙️ 2. Voraussetzungen​

🧩 3. Lokale Entwicklungsumgebung​

🚀 4. Produktionsbereitstellung​

Schritt 1 — Repository klonen​

Schritt 2 — Umgebungsvariablen konfigurieren​

Schritt 3 — Caddy konfigurieren​

Schritt 4 — Redis konfigurieren​

Schritt 5 — Stack starten​

⚙️ 5. Automatisierte Bereitstellung mit GitHub Actions​

🔧 6. Erklärung der Variablen und Secrets​

🔹 Allgemein / Verbindung​

🔹 Anwendung / API-Konfiguration​

🔹 Datenbank und Redis​

🔹 Admin-Panel​

🔹Sicherheit und Sitzungen​

🔹 Benachrichtigungen​

🧱 7. Beispiel: Generierung der .env im Workflow​

💾 8. Persistente Volumes​

🧯 9. Rollback​

🧠 10. Sicherheitsrichtlinien​

📁 11. Wichtige Dateien im Repository​