Keycloak

Keycloak ist eine Open-Source-Softwarelösung für Identity- und Access-Management (IAM), die Single Sign-On (SSO), Authentifizierung und Autorisierung für Anwendungen und Dienste ermöglicht.

Wie funktioniert Keycloak?

Warum verwenden wir Keycloak in unserer Plattform?

✔ Single Sign-On (SSO): Mit Keycloak ermöglichen wir den Benutzern, sich einmal anzumelden und auf alle Teile der Plattform zuzugreifen, was die Benutzererfahrung vereinfacht.
✔ Organisationsfunktion: Keycloak unterstützt die Verwaltung von Benutzern und Ressourcen auf Organisationsebene, sodass Mitglieder nur auf Inhalte ihrer eigenen Organisation zugreifen können.
✔ Sicherheit und Datenschutz: Keycloak sorgt für eine sichere Authentifizierung und schützt die Plattform vor unbefugtem Zugriff.
✔ Datenisolation: Nur Mitglieder einer Organisation sehen die Inhalte ihrer eigenen Organisation, was die Privatsphäre und den Datenschutz gewährleistet.

ProtoGen

Um den Server auszuführen, müssen einige Pakete installiert werden (empfohlen wird die Verwendung von Python venv oder Conda).

Pyannote

1. Installiere Pyannote.audio

pip install pyannote.audio

2. HuggingFace
1. Registriere dich oder melde dich an bei HuggingFace
2. Akzeptiere die Bedingungen
3. Akzeptiere die weiteren Nutzerbedingungen
4. Erstelle einen Zugangstoken auf HuggingFace
5. Kopiere den Zugangstoken an einen sicheren Ort, sodass er nicht öffentlich zugänglich ist.
   (Bei der Nutzung von venv empfehlen wir, ihn in eine Datei .venv/PYANNOTE_KEY zu speichern).
Hinweis: Wenn du einen anderen Speicherort wählst, vergiss nicht, den Pfad "__key_path__" in der Datei src/utils/Annotation.py entsprechend anzupassen.

OpenAI-Schlüssel

Datenbank-Konfiguration

                    {
                        "db_name": "YOUR_DATABASE_NAME",
                        "user_name": "YOUR_USERNAME",
                        "password": "YOUR_PASSWORD",
                        "host": "THE_HOST_RUNNING_THE_DB",
                        "port": 5432
                    }
                        

Keycloak-Konfiguration Um den Server auszuführen, wird eine Keycloak-Konfiguration benötigt. Diese wird in der Datei client_secrets.json im Ordner .venv gespeichert.

Beispiel JSON-Code in einem angepassten Feld

                        {
                            "web": {
                              "issuer": "ISSUER_URI",
                              "auth_uri": "AUTH_URI",
                              "client_id": "CLIENT_ID",
                              "client_secret": "CLIENT_SECRET",
                              "token_uri": "TOKEN_URI",
                              "redirect_uris" : ["REDIRECT_URI"],
                              "userinfo_uri": "USER_INFO_URI"
                            }
                          }
                    

Server lokal ausführen

1. Erstelle eine Python-virtuelle Umgebung und installiere die benötigten Pakete

pip install pyannote.audio

pip install  -r requirements.txt

2. Erstelle die Dateien CHATGPT_API, PYANNOTE_KEY, client_secrets.json, database_metadata.json im .venv-Ordner.
3. Verwende “localhost” als Host in der Datei database_metadata.json.
4. Stelle sicher, dass docker-compose installiert ist.
5. Führe restart_local_server.sh aus:

./restart_local_server.sh;

Chatbot

Chatbot, der Dokumente aus Ihrer Organisation herunterlädt, einbettet und abfragt

Wie es funktioniert:

Verzeichnisstruktur

• open-webui ist die Benutzeroberfläche, mit der du mit dem Chatbot kommunizieren kannst
• Der eigentliche Chatbot ist als Open-WebUI-Pipeline implementiert und befindet sich im Ordner webui_pipeline

Hinweis:

Installation und Ausführung:

1. Repository clonen:

   git clone --recurse-submodules git@github.com:SoftwareEngineering-WS2025-ARMMS/chatbot.git

2. Umgebungsvariablen konfigurieren:
   Damit der Chatbot korrekt mit den anderen Plattformkomponenten verbunden ist, müssen Open-WebUI und der Chatbot konfiguriert werden. Befolge diese Schritte:

   In der Datei ./compose-openwebui anpassen:
   Ändere die folgenden Vatiablen:

   • WEBUI_URL=${WEBUI_URL}: Wo Open-WebUI gehostet wird.
   • WEBUI_SECRET_KEY=${WEBUI_SECRET_KEY}: Geheimschlüssel konfigurieren.
   • OAUTH_CLIENT_ID=${OAUTH_CLIENT_ID}: Keycloak-Client-ID.
   • OAUTH_CLIENT_SECRET=${OAUTH_CLIENT_SECRET}: Keycloak-Client-Geheimschlüssel.
   • OPENID_PROVIDER_URL=${OPENID_PROVIDER_URL}: OpenID-Provider-URL

   Chatbot-Konfiguration:
   Erstelle die Datei ./src/webui_pipeline/pipelines/.env und konfiguriere die folgenden Variablen:

                               OPENAI_KEY=
                               STORAGE_SERVER=
                               ARMMS_SECRET=
                               WEAVIATE_PORT=
                               CACHE_EXPIRY_SECONDS=
                               

   • OPENAI_KEY: Dein API-Schlüssel, der von OpenAI bereitgestellt wird.
   • STORAGE_SERVER: Der Speicher-Server (z. B. dein file-dashboard-backend).
   • ARMMS_SECRET: Ein Organisations-Schlüssel zum Signieren von JWT-Tokens (sollte denselben Wert haben wie der vom Speicher-Engine bereitgestellte Schlüssel).
   • WEAVIATE_PORT: Der Port, auf dem Weaviate lokal gehostet wird (Standard: 8989).
   • CACHE_EXPIRY_SECONDS: Dauer in Sekunden, wie lange ein Dokument maximal im Cache gehalten wird.

   Open-WebUI:

   docker run -d -p 9099:9099 --add-host=host.docker.internal:host-gateway -v pipelines:/app/pipelines --name pipelines --restart always ghcr.io/open-webui/pipelines:main

   docker run -d -p 9099:9099 --add-host=host.docker.internal:host-gateway -v pipelines:/app/pipelines --name pipelines --restart always ghcr.io/open-webui/pipelines:main

3. Container bereitstellen:
   Führe die folgenden Befehle aus, um Weaviate, Open-WebUI und unsere Pipeline bereitzustellen:

   Weaviate starten:

   docker compose -f compose-weaviate.yaml up -d

   Open-WebUI starten:

   docker compose -f compose-openwebui.yaml up -d

   Pipeline starten:

   docker build -t armms-pipeline ./src/webui_pipeline && docker run -d--name armms-pipeline --network=host armms-pipeline

4. Pipeline in Open-WebUI hinzufügen:
   • Stelle die API-URL auf http://host.docker.internal:9099 und den API-Schlüssel auf 0p3n-w3bu!.
     Deine Pipelines sollten jetzt aktiv sein.
5. Konfiguration verwalten:
   • Gehe im Admin-Panel zu Admin Settings > Pipelines.
   • Wähle deine gewünschte Pipeline aus und passe die Werte direkt im WebUI an.

Dashboard

• Tools: Bereits installierte Plugins, bereit zur Nutzung. Durch Doppelklick wird das entsprechende Tool geöffnet
  • ProtoGen
  • Chatbot
• Core: Unterstützende und notwendige Tools zur Nutzung der Plugins.
  Beispiel Dropbox: Upload von Dokumenten, auf die der Chatbot zur Generierung einer Antwort zugreift
• Design: Auswahl zwischen verschiedenen Layouts für das Dashboard
• Layout, Itemgröße, Konfiguration: Individuell anpassbare, erweiterte Einstellungen für das Design des Dashboards

Storage Engine

Abhängigkeiten:

pip install -r requirements.txt

Dropbox:

1. Wählen Sie die Scoped Access API mit vollem Zugriff auf Dropbox während der Erstellung der Anwendung.
2. Aktivieren Sie unter Einstellungen → Entwicklung zusätzliche Benutzer.
3. Redirect-URIs müssen manuell im Abschnitt OAuth2 unter den Einstellungen hinzugefügt werden, auch für lokale Weiterleitungen. Diese URIs müssen mit https:// beginnen (obwohl http:// für localhost erlaubt ist).
4. Die Berechtigungen müssen korrekt gesetzt werden:
• files.content.read
• files.content.write
• files.metadata.read
• files.metadata.write
müssen aktiviert sein.

Umgebungsvariablen:

                                    DROPBOX_APP_KEY=
                                    DROPBOX_APP_SECRET=
                                    ARMMS_SECRET=
                                    DROPBOX_REDIRECT_URI=
                                    CALLBACK_REDIRECT_URI=
                                    KEYCLOAK_JWKS_URL=
                                    

• DROPBOX_APP_KEY und DROPBOX_APP_SECRET werden verwendet, um die erstellte Dropbox-App mit dem Server zu verbinden. Sie finden diese Werte im Abschnitt “App key” und “App secret” in den App-Einstellungen.
• ARMMS_SECRET ist ein Organisations-Schlüssel, der zum Signieren der JWT-Token verwendet wird.
• DROPBOX_REDIRECT_URI wird von Dropbox nach der Anmeldung verwendet. Dies sollte der /dropbox_callback-Endpunkt sein und muss in den Dropbox-App-Einstellungen registriert werden (siehe Schritt 3 im vorherigen Abschnitt).
• CALLBACK_REDIRECT_URI wird verwendet, um den Benutzer nach erfolgreicher Anmeldung weiterzuleiten.
• KEYCLOAK_JWKS_URL wird benötigt, um das Keycloak-Zertifikat für die Validierung der JWT-Token bereitzustellen.

Keycloak-Konfiguration:

                            {
                                 "web": {
                                      "issuer": "ISSUER_URI",
                                      "auth_uri": "AUTH_URI",
                                      "client_id": "CLIENT_ID",
                                      "client_secret": "CLIENT_SECRET",
                                      "token_uri": "TOKEN_URI",
                                      "redirect_uris": ["REDIRECT_URI"],
                                      "userinfo_uri": "USER_INFO_URI",
                                      "logout_uri": "LOGOUT_URI"
                                    }
                                }
                        

Server starten:

Keycloak

Docker Compose: Keycloak und PostgreSQL
Diese Konfiguration definiert eine Docker-basierte Bereitstellung zur Ausführung von Keycloak, einem Identitäts- und Zugriffsverwaltungssystem, mit einer PostgreSQL-Datenbank als persistenter Speicher.

Wichtige Punkte

• Dienste:
• armms-keycloak: Hoster für Keycloak
• keycloakdb: Stellt die Datenbank für Keycloak bereit
• Konfiguration:
• Geheimnisse und Einstellungen werden als Umgebungsvariablen übergeben, die lokal in der Bereitstellungsumgebung festgelegt sind
• Netzwerk:
• Beide Dienste kommunizieren über ein privates Docker-Bridge-Netzwerk

Verwendung

1. Legen Sie die erforderlichen Umgebungsvariablen fest (z. B. Datenbank-Zugangsdaten, Keycloak-Admin-Daten) in der Bereitstellungsumgebung In diesem Beispiel ist der KC_HOSTNAME: https://keycloak-armms.rayenmanai.site, wo Keycloak bereitgestellt wird
2. Starten Sie die Dienste mit folgendem Befehl:

   docker-compose up -d

3. Greifen Sie über den konfigurierten Hostnamen und Port auf Keycloak zu