Zum Inhalt

Deployment

Test-Deployment des Word Web Add-ins für Office 365

Mit docker compose kann Behörden-KlarText zu Test- und Entwicklungszwecken gestartet werden. Für den Produktiveinsatz empfehlen wir, je nach Anzahl der zu erwartenden Nutzerinnen und Nutzer, ein Deployment mit Kubernetes.

Vorbereitung des Test-Deployments

1. Download der Code Repositories

Behörden-KlarText besteht aus mehreren Repositories, die verschiedene Teilaufgaben übernehmen.

Für das Word Web Add-in werden die zwei Repositories Backend und Word Web Add-in benötigt. Zusätzlich kann ein vue-Frontend zu Testzwecken genutzt werden, welches ohne Word funktioniert. Klonen Sie die Repositories mit folgenden Befehlen:

git clone https://gitlab.opencode.de/behoerden-klartext/backend
git clone https://gitlab.opencode.de/behoerden-klartext/word-web-add-in
git clone https://gitlab.opencode.de/behoerden-klartext/frontend

2. Bauen der Docker-Images

Die Docker-Images müssen aus den jeweiligen Repository-Verzeichnissen erstellt werden:

# Backend bauen
cd backend
docker build -t behoerden-klartext/backend .
cd ..

# Word Web Add-in bauen
cd word-web-add-in
docker build -t behoerden-klartext/word-web-add-in .
cd ..

# Frontend bauen
cd frontend
docker build -t behoerden-klartext/frontend .
cd ..

Für das Bauen dieser Docker-Images sollten je nach Internetgeschwindigkeit ungefähr 5 Minuten veranschlagt werden.

3. Ordner für das Test-Deployment erstellen

Erstellen Sie einen neuen Ordner, der als Arbeitsverzeichnis für das Deployment dient.

mkdir -p Behörden-KlarText_Deployment # (1)!
  1. Der Ordnername Behörden-KlarText_Deployment ist ein Beispiel. Sie können den Ordnernamen beliebig anpassen.

4. Konfigurationen kopieren

Kopieren Sie die Beispiel-Konfigurationen aus dem Backend-Repository in den Deployment-Ordner und wechseln Sie in den Deployment-Ordner:

cp -r ./backend/configs/ ./Behörden-KlarText_Deployment/
cd Behörden-KlarText_Deployment/

5. KI-Modelle bereitstellen

Damit Behörden-KlarText funktioniert, muss es auf ein Sprachmodell zugreifen können. Die Anwendung selbst enthält kein integriertes KI-Modell, sondern fungiert als Schnittstelle zu bestehenden Diensten. Die Konfiguration der Verbindung erfolgt in der Datei configs/llm_models.yml.

Hier sehen Sie die gesamte llm_models.yml-Datei
llm_models.yml
# SPDX-FileCopyrightText: 2025-present Bundesministerium für Arbeit und Soziales (BMAS) <info@denkfabrik-bmas.de>
#
# SPDX-License-Identifier: Apache-2.0

behoerden_klartext:
  # first LLM in list will be used as the default; all other LLMs are fallbacks
  gemma_3_27b:                          # internal model id (must be unique!).
    label: gemma3:27b                   # model's name presented to users.
    model: gemma3:27b                   # model name which is used in API call.
    prompt_map: simplify_assistant      # map to load prompts from.
    is_remote: true                     # is this LLM hosted at an external API.
    max_input_length: 9000              # maximum number of characters from the input text used for optimization (independent of the model's context window).
    api:
      url: http://ollama:11434/v1
      health_check: /models             # API endpoint for health check
    inference:
      temperature: 0.1
      top_p: 0.5
      frequency_penalty: 0.0
      presence_penalty: 0.0

  test_model_mock:                     # internal model id (must be unique!).
    label: test_model:mock             # model's name presented to users.
    model: test_model:mock             # model name which is used in API call.
    prompt_map: simplify_assistant     # map to load prompts from.
    is_remote: false                   # is this LLM hosted at an external API.
    max_input_length: 9000             # maximum number of characters from the input text used for optimization (independent of the model's context window).
    api:
      url: http://ollama-mock:11434/v1
      health_check: /models            # API endpoint for health check
    inference:
      temperature: 0.1
      top_p: 0.5
      frequency_penalty: 0.0
      presence_penalty: 0.0

Sie haben zwei Optionen für das Test-Deployment:

  1. Testbetrieb mit Mockup (Standard): Für einen ersten technischen Test wird das ollama-mock Image verwendet. Es liefert vorgefertigte Antworten. Hierfür ist keine Änderung der mitgelieferten Konfiguration notwendig.

  2. Verbindung zu einem echten LLM: Für die echte Nutzung verbinden Sie das Backend mit einer kompatiblen API (z.B. OpenAI, STACKIT Model Serving oder ein lokal laufendes Ollama/vLLM). Passen Sie dazu folgende Werte in der configs/llm_models.yml an:

    • api.url: Die URL des API-Endpunkts.
    • model: Der Name des zu verwendenden Modells.
    • api.auth: (Optional) Authentifizierungsmethode (token oder basic_auth) und Pfad zum Secret, falls der Dienst geschützt ist.

6. Bereitstellung von Secrets

Secrets werden für zugriffsbeschränkte LLM-APIs benötigt. Wenn Ihre in der llm_models.yml definierte API "Basic Auth" oder "Bearer Token" benötigt, müssen die Credentials in einer Secret-Datei hinterlegt werden.

  • Format: username:password (Basic Auth) oder reiner Token-String (Bearer).
  • Initialisierung: Erstellen Sie die Datei, falls dies noch nicht geschehen ist. Wenn kein Passwort benötigt wird (z. B. wenn das ollama-mock Image verwendet wird), genügt es, eine leere Datei zu erstellen:
mkdir -p secrets
touch secrets/llm_api.secret

7. SSL-Zertifikate hinzufügen

Da Microsoft Office Add-Ins zwingend HTTPS voraussetzen, muss für eine Integration in Word eine SSL-gesicherte URL bereitgestellt werden. Im Folgenden wird für Testzwecke das Deployment mit Docker und einem selbst erstellten Zertifikat beschrieben.

Verwenden Sie mkcert, um Zertifikate zu erstellen, und stellen Sie sicher, dass der Key für Docker lesbar ist.

Installieren Sie mkcert

Installieren Sie mkcert (https://github.com/FiloSottile/mkcert) für Ihr Betriebssystem.

mkdir -p certs
mkcert -key-file certs/localhost.key -cert-file certs/localhost.crt localhost 127.0.0.1 ::1
chmod 644 certs/localhost.key
Wie sieht eine erfolgreiche Ausführung aus?

Nachdem Sie die oben stehenden Befehle eingegeben haben, sollten Sie folgende Ausgabe sehen:

Created a new local CA 💥
Note: the local CA is not installed in the system trust store.
Note: the local CA is not installed in the Firefox and/or Chrome/Chromium trust store.
Run "mkcert -install" for certificates to be trusted automatically ⚠️

Created a new certificate valid for the following names 📜
- "localhost"
- "127.0.0.1"
- "::1"

The certificate is at "certs/localhost.crt" and the key at "certs/localhost.key" ✅

It will expire on 26 April 2028 🗓

Behörden-KlarText starten

docker-compose.yml erstellen

Prüfen Sie vor dem Start, dass die Konfiguration und die Secrets für das Backend vorhanden sind, sowie die Zertifikate vorliegen. Fügen Sie folgende Datei als docker-compose.yml ein:

docker-compose.yml
# SPDX-FileCopyrightText: 2025-present Bundesministerium für Arbeit und Soziales (BMAS) <info@denkfabrik-bmas.de>
#
# SPDX-License-Identifier: Apache-2.0

services:
  frontend:
    image: behoerden-klartext/frontend
    ports:
      - 127.0.0.1:54322:9999
    depends_on:
      - backend

  word-web-add-in:
    image: behoerden-klartext/word-web-add-in
    ports:
      - 9999:9999
    environment:
      - ADDIN_URL=https://localhost:9999
      - USE_SSL=true
    volumes:
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - backend

  backend:
    image: behoerden-klartext/backend
    ports:
      - 8000:8000
    secrets:
      - source: llm_api.secret
        target: /backend/secrets/llm_api.secret
    depends_on:
      ollama-mock:
        condition: service_healthy
    volumes:
      - feedback_db:/backend/feedback
      - ./configs:/backend/configs

  ollama-mock:
    image: registry.opencode.de/f13/microservices/base-images/ollama-mock-f13:1.1.0
    restart: on-failure

  otel-collector:
    image: otel/opentelemetry-collector-contrib
    volumes:
      - ./configs/otel_collector.yaml:/etc/otelcol-contrib/config.yaml
    ports:
      - 8889:8889

volumes:
  feedback_db:

secrets:
  llm_api.secret:
    file: ./secrets/llm_api.secret

Services starten

Starten Sie idealerweise den kompletten Verbund:

docker compose up -d

Bei Bedarf können Services auch einzeln gestartet werden:

# Word Web Add-in (https://localhost:9999)
docker compose up -d web-add-in

# Frontend Prototyp (http://localhost:54322)
docker compose up -d frontend

Hier ist ein Beispiel des zu erwartenden Outputs:

[+] Running 5/5
✔ Container behoerden-klartext_deployment-backend-1         Started    6.2s
✔ Container behoerden-klartext_deployment-frontend-1        Started    6.4s
✔ Container behoerden-klartext_deployment-web-add-in-1      Started    6.4s
✔ Container behoerden-klartext_deployment-otel-collector-1  Started    0.2s
✔ Container behoerden-klartext_deployment-ollama-mock-1     Healthy    5.7s

Nach dem Starten der Services kann das Frontend im Browser unter http://localhost:54322/ geöffnet werden.

Behörden-KlarText in Word integrieren

Laden Sie nach dem Starten des Word Web Add-in-Containers das Manifest unter https://localhost:9999/manifest.xml herunter.

Hinweis: In der aktuellen SSL-Nginx-Konfiguration wird Streaming gepuffert. Dies kann dazu führen, dass Echtzeit-Streaming nicht korrekt funktioniert und der optimierte Text als Ganzes angezeigt wird. Dadurch kann es etwas dauern, bis die Antwort angezeigt wird.

Bereitstellung in Microsoft 365

Für den produktiven Einsatz oder weitreichende Tests kann das Add-In im Microsoft 365 Admin Center registriert werden. Das Manifest kann dort direkt als Datei hochgeladen werden.

Sideloading (optional)

Sideloading ist für schnelle lokale Tests gedacht. Microsoft empfiehlt es nicht für produktive Rollouts.

Diese Methode kann direkt in Word im Browser durchgeführt werden. Es wurde mit Microsoft Edge getestet. Weitere Informationen finden Sie in der Microsoft-Dokumentation.

  1. Öffnen Sie Word in Ihrem Browser und ein Dokument.
  2. Wählen Sie Start > Add-ins und dann Weitere Einstellungen oder Weitere Add-Ins.
  3. Im Dialogfeld "Office-Add-ins" wählen Sie Mein Add-in hochladen.
  4. Navigieren Sie zur Manifestdatei des Add-ins und wählen Sie Hochladen.
  5. Das Add-In sollte jetzt im Menüband erscheinen.

Das Add-In kann auch in Word auf dem Desktop geladen werden. Dazu muss das manifest.xml in einem freigegebenen Ordner abgelegt werden:

  1. Öffnen Sie Datei > Optionen.
  2. Navigieren Sie zu Trust Center > Einstellungen für das Trust Center.
  3. Wählen Sie Kataloge vertrauenswürdiger Add-Ins.
  4. Fügen Sie den Netzwerkpfad des freigegebenen Ordners hinzu, in dem sich das Manifest befindet, und aktivieren Sie die Option Im Menü anzeigen.
  5. Starten Sie Word neu.
  6. Wählen Sie Add-Ins > Weitere Add-Ins > geteilter Ordner und dann das Add-In Behörden-KlarText aus.
  7. Das Add-In sollte jetzt im Menüband erscheinen.

Hinweis: Tastenkürzel sind bei dieser Methode nicht verfügbar.

Fehlerbehebung

Beim Test-Deployment erhalte ich folgende Fehlermeldung: bind source path does not exist: /Behörden-KlarText_Deployment/secrets/llm_api.secret. Was ist das Problem?

Beim Starten des Test-Deployments kann folgende Fehlermeldung auftreten:

Error response from daemon: invalid mount config for type "bind": bind source path does not exist: /Behörden-KlarText_Deployment/secrets/llm_api.secret

Möglicherweise haben Sie vergessen, Secrets zu erstellen. Beachten Sie, dass die Datei secrets/llm_api.secret auch benötigt wird, wenn Sie den Testbetrieb mit einem Mockup (ollama-mock Image) durchführen.