Externe Dienste

Im Auslieferungszustand betreibt das Paket alles selbst. Sie können den mitgelieferten Objektspeicher und den mitgelieferten Anmeldeserver durch eigene ersetzen, einen E-Mail-Server anbinden und optionale Integrationen einschalten. All das stellen Sie in .env ein; übernehmen Sie jede Änderung mit:

docker compose up -d

Die mitgelieferten Komponenten wählen Sie mit COMPOSE_PROFILES:

Profil	Komponente
garage	Mitgelieferter S3-Objektspeicher. Entfernen Sie das Profil, um Ihren eigenen S3-Speicher zu verwenden.
keycloak	Mitgelieferter Anmeldeserver. Entfernen Sie das Profil, um Ihr eigenes Keycloak zu verwenden.
backup	Nächtliche Backups (siehe Backups).

Die Vorgabe ist COMPOSE_PROFILES=garage,keycloak.

Eigener S3-Speicher

GOAT speichert hochgeladene Dateien in einem S3-Bucket und Profilbilder und Bilder in einem zweiten, öffentlich lesbaren Bucket. Jeder S3-kompatible Speicher ist geeignet.

Vor dem ersten Start entscheiden

Richten Sie Ihren eigenen Speicher ein, bevor Sie GOAT zum ersten Mal starten. Daten, die bereits im mitgelieferten Garage liegen, werden nicht in Ihren Speicher übertragen.

1. Buckets vorbereiten

• Upload-Bucket (S3_BUCKET_NAME, Vorgabe goat-uploads). Browser laden Dateien direkt in diesen Bucket hoch, daher müssen seine CORS-Regeln PUT mit einem Content-Type-Header von der GOAT-URL erlauben. Das mitgelieferte Garage verwendet diese Regel, die Sie anpassen können:

  [
    {
      "AllowedOrigins": ["https://goat.example.org"],
      "AllowedMethods": ["GET", "HEAD", "PUT"],
      "AllowedHeaders": ["*"],
      "ExposeHeaders": ["ETag"],
      "MaxAgeSeconds": 3600
    }
  ]

• Assets-Bucket (ASSETS_BUCKET_NAME, Vorgabe goat-assets) für Profilbilder und Bilder. Er muss ohne Zugangsdaten unter der Adresse lesbar sein, die Sie als ASSETS_URL eintragen. Erlaubt Ihr Speicher keinen öffentlich lesbaren Bucket, lassen Sie ihn weg: Setzen Sie ASSETS_SERVED_BY_CORE=true und ASSETS_URL=<GOAT_PUBLIC_URL>/api/v2/asset/file. GOAT legt die Bilder dann im Upload-Bucket unter assets/ ab und liefert sie selbst aus.

Auf beide Buckets wird mit demselben Zugangsschlüssel zugegriffen.

2. .env einrichten

Entfernen Sie garage aus COMPOSE_PROFILES und setzen Sie:

Einstellung	Bedeutung
S3_ENDPOINT_URL	Der S3-Endpunkt, wie der Server ihn erreicht, z. B. https://s3.example.org
S3_PUBLIC_ENDPOINT_URL	Der S3-Endpunkt, wie Browser ihn erreichen; Upload-Links zeigen hierhin
S3_REGION	Die Region, z. B. eu-central-1
S3_BUCKET_NAME	Der Upload-Bucket
S3_FORCE_PATH_STYLE	true für Adressen im Pfad-Stil (endpunkt/bucket/key), false für den Virtual-Hosted-Stil (bucket.endpunkt/key)
S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY	Ihr Zugangsschlüssel. Ersetzen Sie die Werte, die setup.sh für Garage erzeugt hat.
ASSETS_S3_ENDPOINT_URL	Endpunkt des Assets-Buckets; Vorgabe ist S3_ENDPOINT_URL
ASSETS_BUCKET_NAME	Der Assets-Bucket
ASSETS_URL	Öffentliche Adresse des Assets-Buckets, z. B. https://assets.example.org
ASSETS_SERVED_BY_CORE	true legt die Bilder im Upload-Bucket ab und lässt GOAT sie ausliefern, für Speicher ohne öffentlichen Bucket

GARAGE_RPC_SECRET und GARAGE_ADMIN_TOKEN werden ohne das mitgelieferte Garage nicht verwendet.

Eigenes Keycloak

GOAT kann statt des mitgelieferten Keycloak ein Keycloak verwenden, das Sie bereits betreiben.

Anforderungen an den Client

Legen Sie in Ihrem Realm einen Client für GOAT mit diesen Einstellungen an:

Einstellung	Wert
Client-Typ	Vertraulich (Client-Authentifizierung an), mit aktiviertem Standard Flow
Valid redirect URIs	<GOAT-URL>/*, z. B. https://goat.example.org/*
Web origins	<GOAT-URL>
Service-Account	Aktiviert, mit den realm-management-Rollen view-users und manage-users

GOAT verwendet den Service-Account, um Benutzerkonten zu lesen, Name und E-Mail-Adresse eines Benutzers in Keycloak mit seinem GOAT-Profil abzugleichen und ein Konto zu löschen, wenn sein Benutzer es in GOAT löscht.

Im Standardmodus des KI-Assistenten muss im Realm Revoke Refresh Token ausgeschaltet sein (Realm settings, Tokens), damit der Assistent die Anmeldung bei langen Antworten erneuern kann; siehe KI-Assistent.

.env einrichten

Entfernen Sie keycloak aus COMPOSE_PROFILES und setzen Sie:

Einstellung	Bedeutung
KEYCLOAK_PUBLIC_URL	Keycloak, wie Browser es erreichen, z. B. https://login.example.org
KEYCLOAK_INTERNAL_URL	Keycloak, wie die GOAT-Container es erreichen; oft dieselbe URL
REALM_NAME	Ihr Realm
KEYCLOAK_CLIENT_ID	Die Client-ID
KEYCLOAK_CLIENT_SECRET	Das Client-Secret. Ersetzen Sie den Wert, den setup.sh erzeugt hat.

Beide URLs enthalten den relativen Pfad Ihres Keycloak, falls es einen verwendet, etwa /auth: https://login.example.org/auth.

Der erste Administrator und smoke.sh

Mit Ihrem eigenen Keycloak legt GOAT dort keinen Benutzer an. smoke.sh meldet sich mit GOAT_ADMIN_EMAIL und GOAT_ADMIN_PASSWORD über eine direkte Passwort-Anmeldung an. Damit das funktioniert, setzen Sie beide auf einen bestehenden Benutzer Ihres Realms und aktivieren Sie Direct access grants am Client.

Verwendet Ihr Keycloak ein Zertifikat einer privaten CA, lesen Sie Firmen-CA.

Ein Realm, den sich GOAT mit anderen Anwendungen teilt

Jeder Client eines Realms kann ein Token bekommen, das mit dem Schlüssel des Realms signiert ist, und standardmäßig nehmen die GOAT-APIs ein solches Token auch dann an, wenn Keycloak es für eine andere Anwendung ausgestellt hat. Eine Regel, die nur bestimmte Benutzer bei GOAT anmeldet, etwa eine Gruppenprüfung am Client von GOAT, schützt dann die Anmeldeseite, aber nicht die APIs.

Setzen Sie AUTH_ALLOWED_CLIENTS auf die Clients, deren Tokens GOAT annimmt, durch Kommas getrennt:

AUTH_ALLOWED_CLIENTS=goat

GOAT prüft dann bei jedem Token den Claim azp, also den Client, für den Keycloak es ausgestellt hat, und beantwortet ein Token jedes anderen Clients mit 401. Die Liste muss KEYCLOAK_CLIENT_ID enthalten: Die Web-App meldet Benutzer mit diesem Client an, und der Druck-Worker und die Dienste von GOAT reichen diese Tokens weiter. Ohne ihn könnte niemand GOAT verwenden, daher startet der Container core dann nicht und nennt beide Einstellungen. Ergänzen Sie jeden weiteren Client, dessen Tokens die GOAT-APIs erreichen sollen, etwa einen, mit dem sich Ihre eigenen Skripte anmelden. Die Prüfung erfordert keine Änderung am Realm. Übernehmen Sie sie mit docker compose up -d.

Was die Prüfung nicht abdeckt

Die Prüfung betrifft die Anwendung, für die ein Token ausgestellt wurde, nicht den Benutzer.

• Dürfen nur bestimmte Benutzer GOAT verwenden, etwa die Mitglieder einer Gruppe, setzen Sie das am Client von GOAT für jeden Weg durch, auf dem er Tokens ausstellt: die Anmeldung im Browser und, falls aktiviert, Direct access grants (eine direkte Passwort-Anmeldung, die Keycloak über einen eigenen Ablauf abwickelt). Andernfalls schalten Sie Direct access grants am Client aus. Sonst könnte ein Benutzer außerhalb der Gruppe über den Weg, den Ihre Regel nicht abdeckt, ein Token des GOAT-Clients bekommen, und die GOAT-APIs würden es annehmen. smoke.sh benötigt Direct access grants (siehe oben).
• Die Web-App hält Benutzer mit einem Refresh-Token angemeldet, daher bleibt ein Benutzer, den Sie aus dieser Gruppe entfernen, angemeldet, bis die Sitzung endet. Um sie sofort zu beenden, melden Sie den Benutzer in Keycloak ab, einschließlich seiner Offline-Sitzungen.

E-Mail

GOAT versendet Einladungen und Keycloak E-Mails zum Zurücksetzen des Passworts über einen SMTP-Server. E-Mail ist ausgeschaltet, solange SMTP_HOST leer ist.

Einstellung	Bedeutung
SMTP_HOST, SMTP_PORT	Der Mailserver, z. B. smtp.example.org und 587
SMTP_SECURITY	starttls (meist Port 587), ssl (meist Port 465) oder none (z. B. ein internes Relay auf Port 25)
SMTP_USER, SMTP_PASSWORD	Die Anmeldedaten. Lassen Sie beide leer für ein Relay, das E-Mails ohne Anmeldung annimmt.
SMTP_FROM	Absenderadresse. Vorgabe ist SMTP_USER, daher ist sie für ein Relay ohne Anmeldung Pflicht.
EMAILS_FROM_NAME	Absendername, Vorgabe GOAT

Zum Beispiel ein Relay in Ihrem Netz:

SMTP_HOST=mail.internal.example.org
SMTP_PORT=25
SMTP_SECURITY=none
SMTP_USER=
SMTP_PASSWORD=
SMTP_FROM=goat@example.org

Führen Sie nach einer Änderung von SMTP_SECURITY einmal ./setup.sh aus: Es leitet die beiden Schalter SMTP_STARTTLS und SMTP_SSL ab, die Keycloak benötigt. Übernehmen Sie die Änderung dann mit docker compose up -d.

Mit starttls oder ssl prüfen GOAT und Keycloak das Zertifikat des Relays gegen die öffentlichen Zertifizierungsstellen. Stammt das Zertifikat Ihres Relays von einer Firmen-CA, setzen Sie GOAT_CA_BUNDLE wie unter Firmen-CA beschrieben; sonst schlägt der Versand mit einem Zertifikatsfehler fehl.

Ein Ort für die E-Mail-Einstellungen

Das mitgelieferte Keycloak verwendet dieselben SMTP-Einstellungen: Bei jedem docker compose up -d überträgt der Schritt keycloak-sync sie aus .env in den Realm. Ändern Sie sie nur in .env; Änderungen in der Keycloak-Admin-Konsole unter Realm settings → Email werden beim nächsten Start ersetzt.

E-Mail-Branding

Standardmäßig zeigen die E-Mails von GOAT und von Keycloak den Namen GOAT und keine Links in der Fußzeile. Mit diesen optionalen Einstellungen fügen Sie in beiden Ihre eigenen hinzu:

Einstellung	Bedeutung
EMAIL_BRAND_NAME	Name, der in den E-Mails erscheint
EMAIL_LOGO_URL	Adresse eines Logo-Bildes, das statt des Namens erscheint
EMAIL_CONTACT_URL	Kontakt-Link in der Fußzeile. Die App verwendet ihn auch für ihre Kontakt-Links.
EMAIL_PRIVACY_URL	Link zur Datenschutzerklärung in der Fußzeile. Auch die Anmeldeseite verlinkt darauf.
EMAIL_COMPANY_NAME	Wer Ihr GOAT betreibt, als Zeile in der Fußzeile, z. B. Name und Anschrift Ihrer Organisation. Entfällt, solange leer.
EMAIL_COMPANY_URL	Website, auf die diese Zeile verlinkt.

Die Bilder in den E-Mails kommen von GOATs öffentlicher URL (<öffentliche URL>/assets) oder von STATIC_ASSETS_URL, falls gesetzt. Die Mailprogramme der Empfänger laden sie von dort, die Adresse muss für sie also erreichbar sein.

Support-Tickets

GOAT kann Problemmeldungen und Fragen seiner Benutzer an einen Odoo-Helpdesk weiterreichen, wo sie als Tickets mit Antworten erscheinen. Das ist optional und standardmäßig aus. Ohne diese Einstellungen zeigt Problem melden in der App eine E-Mail-Adresse und den Link Dokumentation, und die Routen unter /api/v2/support antworten mit 404, außer /api/v2/support/summary, die der App mitteilt, dass der Support aus ist. Der Link Feedback des KI-Assistenten öffnet dieselbe Adresse. Sie ist standardmäßig support@plan4better.de; Ihre eigene legen Sie mit NEXT_PUBLIC_SUPPORT_EMAIL fest, siehe Konfigurationsreferenz.

Einstellung	Bedeutung
ODOO_URL	Adresse des Odoo, z. B. https://odoo.example.org. Gemeinsam für GOATs Odoo-Anbindungen.
ODOO_DB	Die Odoo-Datenbank. Gemeinsam für GOATs Odoo-Anbindungen.
ODOO_SUPPORT_API_KEY	API-Schlüssel des Support-Benutzers in diesem Odoo. Er ist ein Geheimnis.
ODOO_SUPPORT_TEAM_ID	Numerische ID des Helpdesk-Teams, das die Tickets erhält
ODOO_SUPPORT_POST_ACTION	Optional. Name der Odoo-Serveraktion, die eine Nachricht als Teilnehmer des Tickets veröffentlicht. Vorgabe GOAT: post message as ticket participant.

Support-Tickets sind nur eingeschaltet, wenn die ersten vier Einstellungen alle gesetzt sind; ist eine davon leer, bleiben sie aus. Den API-Schlüssel stellt Plan4Better für sein eigenes Odoo aus. Lassen Sie auf Ihrer eigenen Installation alle vier leer, es sei denn, Sie haben einen erhalten.

Nachrichten zu einem Ticket können Anhänge von bis zu 55 MiB in einer Anfrage enthalten. Das mitgelieferte Caddy setzt keine Grenze für Anfragekörper. Stellen Sie einen eigenen Proxy oder Load Balancer davor, muss er für /api/v2/support Anfragekörper von mindestens 56 MB annehmen und großzügige Lese-Timeouts erlauben.

Ohne Anmeldung

Für lokale Tests und Demos kann GOAT ganz ohne Anmeldung laufen:

AUTH=False

Alle, die GOAT öffnen, handeln dann als ein eingebauter Administrator.

warnung

Mit AUTH=False hat jeder, der die URL erreicht, vollen Zugriff auf alle Daten. Verwenden Sie diese Einstellung nur für lokale oder Demo-Installationen.

KI-Assistent

Der Assistent gehört zu jeder Installation. Er bleibt verborgen, bis ein Sprachmodell eingerichtet ist, auf einem von zwei Wegen:

• GOAT AI für alle Organisationen. Richten Sie die eingebaute Verbindung in .env ein, zum Beispiel:

  ASSISTANT_DEFAULT_PROVIDER=openai_compatible
  ASSISTANT_DEFAULT_MODEL=<Modell-ID>
  ASSISTANT_DEFAULT_BASE_URL=https://llm.example.org/v1
  ASSISTANT_DEFAULT_API_KEY=<Schlüssel>

  Welche von ASSISTANT_DEFAULT_API_KEY, ASSISTANT_DEFAULT_BASE_URL und ASSISTANT_DEFAULT_REGION ein Anbieter braucht, steht in der Konfigurationsreferenz.

• Eine eigene Verbindung der Organisation. Ein Administrator der Organisation legt sie unter Einstellungen → KI an. Die Zugangsdaten werden mit ASSISTANT_SECRETS_KEY verschlüsselt gespeichert, den setup.sh erzeugt.

Übernehmen Sie Änderungen mit docker compose up -d. Danach finden die Benutzer KI fragen in der oberen Leiste.

Amazon Bedrock und Google Vertex AI ohne API-Schlüssel verwenden ihre eigenen Zugangsdaten. Legen Sie diese in einer Datei assistant.env neben .env ab; nur der Assistent liest sie:

# assistant.env
AWS_ACCESS_KEY_ID=<Schlüssel-ID>
AWS_SECRET_ACCESS_KEY=<Geheimnis>
# oder für Vertex AI eine Dienstkonto-Datei in ./certs:
# GOOGLE_APPLICATION_CREDENTIALS=/certs/vertex.json

Diese Zugangsdaten gelten nur für GOAT AI, nie für eigene Verbindungen der Organisationen. Der Assistent läuft in seinem Container als Benutzer appuser; eine Schlüsseldatei in ./certs muss für ihn lesbar sein (zum Beispiel chmod 644).

Lange Antworten und Keycloak. Eine Antwort läuft weiter, wenn der Browser geschlossen wird. Dauert sie länger als die Anmeldung, erneuert der Assistent die Anmeldung mit dem Keycloak-Client der Web-App, dem in KEYCLOAK_CLIENT_ID. Im Realm Ihres eigenen Keycloak muss deshalb Revoke Refresh Token ausgeschaltet sein (Realm settings, Tokens); der mitgelieferte Realm ist so eingerichtet.

Mit Keycloak 26.2 oder neuer können Sie stattdessen Token Exchange verwenden (ASSISTANT_TOKEN_EXCHANGE_ENABLED=true). Legen Sie für den Assistenten einen vertraulichen (confidential) Client an und tragen Sie ihn in ASSISTANT_KEYCLOAK_CLIENT_ID und ASSISTANT_KEYCLOAK_CLIENT_SECRET ein. Zwei Einstellungen sind Pflicht; ohne sie schlägt jede Antwort gleich zu Beginn fehl:

• Schalten Sie am Client des Assistenten Allow refresh token in Standard Token Exchange ein.
• Fügen Sie am Client der Web-App einen Audience-Mapper hinzu, der den Client des Assistenten in den Claim aud des Access-Tokens aufnimmt.

Mit Token Exchange ist Revoke Refresh Token nicht erforderlich, weil der Assistent ein eigenes Refresh-Token erhält. Das mitgelieferte Keycloak hat Version 22 und unterstützt Token Exchange nicht.

Firmen-CA. Der Assistent vertraut GOAT_CA_BUNDLE zusätzlich zu den öffentlichen CAs, für Modellserver, die Dienste von GOAT und Keycloak, wie die anderen Dienste; siehe Firmen-CA. Weitere Einstellungen sind nicht nötig.

Modellserver im eigenen Netz. Eine Verbindung einer Organisation darf keine privaten oder internen Adressen erreichen, außer mit ASSISTANT_ALLOW_PRIVATE_ENDPOINTS=true. GOAT AI richten Sie selbst ein; dafür gilt diese Grenze nicht.

Externe Agenten erreichen den MCP-Endpunkt von GOAT unter <GOAT_PUBLIC_URL>/assistant/mcp mit einem Anmelde-Token von GOAT. Der Endpunkt beantwortet nur Anfragen für den Hostnamen von GOAT (GOAT_HOSTNAME), und die frühere Adresse des Katalogs, /catalog/mcp, gibt es nicht mehr. Die Aufzeichnungen der Werkzeugaufrufe über MCP werden ASSISTANT_MCP_AUDIT_RETENTION_DAYS Tage aufbewahrt.

Datenbank. Der Assistent verbindet sich mit dem Datenbankbenutzer von GOAT, dem die Datenbank gehört. Das braucht er, weil die Berechtigungsprüfungen von GOAT mit den Rechten des Aufrufers laufen und viele Tabellen von GOAT lesen. Die Rechte prüfen Sie mit:

docker compose exec assistant python -m assistant.dbcheck

Der Befehl gibt ok aus oder listet jedes fehlende Recht auf.

Datenverarbeitung. Fragen von Benutzern und, je nach Datenrichtlinie der Organisation, Daten aus GOAT gehen an den Modellanbieter der verwendeten Verbindung. Bei GOAT AI ist das der Anbieter, den Sie einrichten; bei einer eigenen Verbindung der Anbieter der Organisation. Die Datenrichtlinie einer Organisation ist Eingeschränkt, bis eine Administratorin oder ein Administrator der Organisation unter Einstellungen → KI Standard wählt: Bis dahin verlassen nur Feldnamen, Typen, Anzahlen und Statistiken GOAT, niemals Zeilen oder Geometrien.

Optionale Integrationen

GOAT funktioniert ohne jede dieser Integrationen. Jede schaltet eine Funktion frei, die einen externen Dienst benötigt.

Einstellung	Was sie freischaltet	Ohne sie
NEXT_PUBLIC_MAPTILER_KEY	Die Satelliten-/Hybrid-Grundkarte von MapTiler	Diese Grundkarte wird ausgeblendet; die anderen Grundkarten funktionieren
NEXT_PUBLIC_MAPBOX_TOKEN	Die Ortssuche im Suchfeld der Karte (über Mapbox)	Das Suchfeld findet keine Orte
CATALOG_S3_BUCKET, CATALOG_S3_ENDPOINT_URL, CATALOG_S3_ACCESS_KEY_ID, CATALOG_S3_SECRET_ACCESS_KEY, CATALOG_S3_REGION	Den GOAT-Datenkatalog: ein schreibgeschützter Bucket mit den harmonisierten Datensätzen, der regelmäßig gespiegelt wird. Er enthält auch den Spiegel von OpenStreetMap und Overture Maps (Details)	Der Katalog bleibt leer, seine Synchronisierung ist ausgeschaltet, und die Bereiche OpenStreetMap und Overture Maps finden keine Daten
GEOCODING_URL, GEOCODING_AUTHORIZATION	Den Geocoding-Dienst, den Analyse-Werkzeuge verwenden	Analyseschritte, die Geocoding benötigen, können nicht laufen
OTEL_ENABLED, OTEL_EXPORTER_OTLP_ENDPOINT	Den Export von Traces, Metriken und Logs an Ihren OpenTelemetry-Collector	Es wird nichts exportiert

Die Links, die in der App erscheinen, und die Quelle der Produktgrafiken finden Sie in der Konfigurationsreferenz. Die Quelle der Routing-Basisdaten ist unter Routing-Basisdaten beschrieben.

OpenStreetMap und Overture Maps

Die Bereiche OpenStreetMap und Overture Maps unter Layer hinzufügen › Daten abrufen / verbinden kopieren die Features eines Gebiets in einen GOAT-Layer. Sie lesen aus einem Spiegel beider Datensätze, der als GeoParquet im Katalog-Bucket (CATALOG_S3_*) unter mirror/osm und mirror/overture liegt. Der Spiegel gehört nicht zu einer GOAT-Installation; eine eigene Pipeline legt ihn dort neben dem Katalog ab. Zwei Teile von GOAT lesen ihn: processes füllt die Attribut- und Wertelisten im Dialog, und der Windmill-Worker tools führt das Kopieren aus. Mehr ist nicht einzustellen: Ohne Katalog-Bucket finden die beiden Bereiche keine Daten.

Die Lizenz wird an jedem neuen Layer vermerkt: ODbL 1.0 für OpenStreetMap, CDLA-Permissive 2.0 für Overture-Orte und ODbL 1.0 für die übrigen Overture-Typen.