bifroest/docs/einrichtung.md

Einrichtung nach dem Start: alles integrieren

Diese Anleitung setzt dort an, wo scripts/dev.sh --reset (oder --setup plus uv run aiw demo) aufhört. Danach gibt es schon:

• Demo-Team mit den Nutzern admin (Plattform-Admin), entwicklung, fachbereich und freigabe (Freigeber in den Demo-Workspaces), Passwort aus AIW_DEMO_PASSWORD
• die Workspaces „Demo: Bestellservice“ (mit Shop-Datenbank), „Demo: MCP-Entwicklung“ und „Demo: Nur Chat“ (ohne Datenquellen, zum Vergleich)
• den Datenbank-Treiber PostgreSQL und die eingebauten Tools, nach Vorschlag eingestuft

Zum Abhaken in kurz: Checkliste. Diese Fassung ist für Entwicklung und Betrieb: mit .env, lokalen Diensten und Ports. Die reinen Klickwege stehen auch in der Online-Hilfe: Für Plattform-Admins → Ersteinrichtung (/hilfe/plattform-admin#ersteinrichtung) und Für Workspace-Admins → Workspace startklar machen (/hilfe/workspace-admin#workspace-startklar-machen). Ändert sich ein Klickweg, beide Stellen anpassen.

Alles Weitere richtest du als admin unter http://127.0.0.1:8765 ein. Reihenfolge: erst das Pflichtprogramm (1–2), dann, was du brauchst (3–8). Änderungen an .env wirken erst nach einem Neustart von scripts/dev.sh.

Nr.	Was	Pflicht?	Ohne geht nicht …
1	Modell	ja	überhaupt eine Antwort
2	Tools prüfen	ja	Tool-Aufrufe (sonst gesperrt)
3	Munin (Gedächtnis)	nein	Merken über Chats hinweg
4	Hugin (Regeln, Skills, Befehle)	nein	Pakete, Slash-Befehle
5	Dokumenten-Auslese	nein	Office, PDF, Bilder in abgeglichenen Ordnern
6	Bitbucket	nein	Pushen und Pull Requests auf einen echten Server
7	Benachrichtigungen	nein	E-Mails zu Freigaben, Teams/Slack
8	Weiteres	nein	eigene Nutzer, Oracle, eigene MCP-Server

1. Modell (Pflicht)

Wo: Administration → Modelle und Zugänge

1. Endpunkt anlegen: Name (z. B. „OpenAI“) und Basis-URL einer OpenAI-kompatiblen Responses API, z. B. https://api.openai.com/v1. Später kommt hier das AI Gateway dazu.
2. API-Key hinterlegen: am Endpunkt einen Key für alle Teams (lokal am einfachsten) oder je Team. Er wird verschlüsselt gespeichert; angezeigt werden nur die letzten Zeichen.
3. Modell hinzufügen: Modell-ID beim Anbieter (z. B. gpt-6-luna), Bezeichnung, Kontextgröße und, wenn du Kosten sehen willst, Preise je Million Tokens. Das erste Modell wird Standard.
4. Verbindung testen am Modell.

Klappt, wenn: In einem Demo-Workspace oben „Modell …“ steht und eine Beispielfrage unter Ausprobieren eine Antwort bekommt.

Ein Workspace kann unter Einstellungen → Allgemein → Modell ein anderes Modell wählen.

2. Tools prüfen (Pflicht)

Wo: Administration → Tools

Die Demo hat die eingebauten Tools nach Vorschlag eingestuft. Prüfe trotzdem:

• Stehen Tools auf nicht eingestuft, z. B. nach einem Update oder bei neuen MCP-Servern: Vorschläge übernehmen (nur eingebaute Tools) oder einzeln einstufen. Nicht eingestufte Tools sind für die KI gesperrt.
• Die Voreinstellung: read und write_internal erlaubt, write_external mit Freigabe, destructive gesperrt. Strenger geht es global hier oder je Workspace unter Einstellungen → Tools.

Klappt, wenn: Die Beispielfrage „Was hat sich in den letzten zwei Wochen im Repository geändert?“ Tool-Aufrufe zeigt (aufklappbar unter der Antwort) und keine Meldung „nicht verfügbar“.

3. Munin: Gedächtnis

Munin läuft als zentraler MCP-Dienst (Streamable HTTP). Du brauchst seine URL, für die Registrierung ggf. ein Token, und je Workspace einen Munin-Key; der Key bestimmt das Projekt in Munin.

Plattform-Admin, einmalig: Administration → MCP-Server

1. Server anlegen: Kurzname munin, Bezeichnung „Munin“, URL (z. B. https://munin.intern/mcp), Art: Gedächtnis. Der Host muss in AIW_MCP_ALLOWED_HOSTS stehen; lokal (localhost) erlaubt scripts/dev.sh ihn ohnehin.
2. Tools abrufen. Die Seite zeigt die Anleitung des Servers.
3. Empfehlung übernehmen: Lesen und Merken erlaubt, forget gesperrt. Löschen dürfen nur Menschen.

Workspace-Admin, je Workspace: Einstellungen → MCP-Server → Zentrale Server

4. Munin mit dem Munin-Key des Projekts freischalten.

Klappt, wenn: Im Chat „Merk dir: Deployments nie freitags nach 14 Uhr.“ einen Eintrag erzeugt, der unter Gedächtnis (Seitenleiste des Workspace) erscheint, und ein neuer Chat ihn auf Nachfrage kennt.

4. Hugin: Regeln, Skills und Befehle

Hugin ist das Register für geprüfte KI-Erweiterungen. Lokal zum Ausprobieren: im Repository hugin scripts/demo.sh starten (Server auf http://127.0.0.1:8080); den Integrations-Key „Softwareverteilung“ (hi_…, Tenant shop) findest du in .demo/keys.txt.

Plattform-Admin, einmalig: Administration → Hugin

1. Host eintragen, z. B. http://127.0.0.1:8080 → „Hugin ist erreichbar“. Mit AIW_HUGIN_URL in .env ist er vorausgefüllt.

Workspace-Admin, je Workspace: Einstellungen → Hugin

2. Unter Zugang den Integrations-Key (hi_…) eintragen → Bifröst zeigt Tenant und Key-Name. In Hugin legt man ihn unter Integrationen mit den Rollen Lesen und Ausliefern an.
3. Pakete wählen (z. B. pub-release-notiz), Abgleichen, Übernehmen. Übernommene Pakete sind festgeschrieben; Updates prüft der Worker im Hintergrund.

Plattform-Admin: Falls unter Tools load_skill, read_skill_file oder hugin_feedback noch nicht eingestuft sind, jetzt einstufen.

Klappt, wenn: Im Chat / die Befehle aus Hugin vorschlägt und Antworten unten „Hugin: …“ mit den geltenden Paketen zeigen.

5. Dokumenten-Auslese für abgeglichene Ordner

Textdateien (Markdown, TXT, CSV …) liest Bifröst selbst. Für Office, PDF und Bilder braucht es den zentralen MCP-Server, der den Dateiinhalt als Base64 nimmt und Text liefert.

Plattform-Admin: Administration → MCP-Server

1. Server anlegen mit URL und Art: Dokumenten-Auslese, Tools abrufen.
2. Auf der Seite des Servers unter Dokumenten-Auslese: das Tool wählen, den Parameter für den Inhalt (Base64) und optional den für den Dateinamen. Speichern.

Die KI ruft dieses Tool nicht selbst auf; der Worker schickt neue und geänderte Dateien hin. Grenzen in .env: AIW_DOC_MAX_MB, AIW_DOC_MAX_FILES, AIW_DOC_MAX_TEXT_KB, AIW_DOC_EXTRACT_TIMEOUT_SECONDS.

Klappt, wenn: Unter Daten → Abgeglichene Ordner eine DOCX- oder PDF-Datei nach kurzer Zeit von „wird ausgelesen“ auf „lesbar“ wechselt. Ordner abgleichen geht am bequemsten in Chrome oder Edge.

6. Bitbucket: pushen und Pull Requests

Die Demo-Repositories liegen lokal (file://…); Branches der KI bleiben dort. Für einen echten Server:

Workspace-Admin: Daten → Verbinden → Git-Repository (oder eine vorhandene Quelle Bearbeiten)

1. HTTPS-URL, Ziel-Branch (meist main) und ein Token. Bei Bitbucket Data Center ein HTTP-Access-Token; bei anderen Servern (Gitea, Forgejo, GitLab, GitHub) Token plus Nutzername.
2. Unter Pull Requests „Bitbucket Data Center“ wählen. Ohne das kann man Branches nur pushen.
3. Der technische Account braucht Schreib- und Löschrechte auf ai/* (Branch Permission). Der Host muss in AIW_GIT_ALLOWED_HOSTS stehen.

Klappt, wenn: Nach einer Änderung durch die KI unter Änderungen „Branch pushen“ bzw. „Pull Request erstellen“ funktioniert und im Bereich Repository → Pull Requests die offenen PRs erscheinen.

7. Benachrichtigungen

E-Mail (Plattform): in .env

AIW_SMTP_HOST=smtp.intern
AIW_SMTP_PORT=587
AIW_SMTP_USER=...
AIW_SMTP_PASSWORD=...
AIW_SMTP_FROM=bifroest@firma.de
AIW_PUBLIC_URL=http://127.0.0.1:8765   # Basis für Links in E-Mails

Jede Person trägt ihre Adresse im Profil ein (Klick auf den Namen oben rechts). Stand der Zustellung: Administration → Benachrichtigungen.

Teams oder Slack (je Workspace): Einstellungen → Allgemein → Benachrichtigungen, Webhook-URL eintragen. Erlaubte Hosts stehen in AIW_WEBHOOK_ALLOWED_HOSTS.

Klappt, wenn: Ein Tool mit Freigabe (z. B. ein schreibendes MCP-Tool) eine E-Mail bzw. eine Nachricht an die Freigebenden auslöst.

8. Weiteres nach Bedarf

• Eigene Nutzer und Teams: Administration → Teams und → Nutzer. Neue Nutzer bekommen ein Einmal-Passwort und setzen beim ersten Login ein eigenes. Im Workspace unter Einstellungen → Mitglieder aufnehmen; Rollen: Mitglied, Freigeber, Admin.
• Oracle: scripts/dev.sh --oracle startet Container und DB-Dienst (Port 8792). Treiber unter Administration → Datenbank-Treiber registrieren (URL und Schlüssel zeigt das Skript), Tools abrufen, einstufen; dann im Workspace eine Datenbank mit Service-Name FREEPDB1 verbinden.
• Eigene MCP-Server: zentral unter Administration → MCP-Server oder je Workspace unter Einstellungen → MCP-Server → Eigene Verbindungen. Neue Tools einstufen (die Annotations sind nur ein Vorschlag). Was ein eigener Server mitbringen sollte, zeigt die Demo „MCP-Entwicklung“ (MCP-Unterlagen).
• Globale Approver: unter Administration → Nutzer einzelne Personen als Globaler Approver markieren; unter Administration → Tools bei einem Tool die Freigabestufe „global“ wählen. Solche Anträge entscheiden dann nur sie, nicht die Workspace-Admins.

Abschluss: alles einmal durchprobieren

• Bestellservice: die acht Beispielfragen, darunter Repository, Bestelldaten mit Diagramm, Dokumente, Shop-Datenbank und die Rabatt-Änderung (Commit auf ai/…).
• MCP-Entwicklung: Annotations prüfen, Review gegen Code, langsamste Tools als Diagramm.
• Munin merkt sich etwas, Hugin-Befehl mit / funktioniert, eine DOCX wird lesbar.
• Antworten mit 👍/👎 bewerten; unter Nutzung und Kosten erscheinen Verbrauch und Rückmeldungen.

Ausführliche Prüfschritte stehen im Testplan, die Bedienung in der Online-Hilfe (Knopf Hilfe oben).