Licensed to be used in conjunction with basebox, only.
// installation
basebox Server FAQ
Gilt für
Produkt: Server · Zielgruppe: Platform Operator
Installation
Wie installiere ich basebox Server?
Nutzen Sie einen dieser Wege:
- Server Preparation Guide für die Infrastruktur-Voraussetzungen
- Lokaler Schnellstart für
basebox.local-Installationen - Helm Charts verwenden für echte Domains, cert-manager oder bestehende TLS-Secrets
- Deployment-Topologien für getrennte basebox- und Inferenzserver
Können basebox und LLM-Inferenz auf getrennten Servern laufen?
Ja. basebox kann auf einem reinen CPU-Anwendungsserver laufen, während AISRV einen geschützten OpenAI-kompatiblen Inferenz-Endpunkt auf einem separaten GPU-Server aufruft. Deaktivieren Sie das gebündelte Inferenz-Chart, konfigurieren Sie den externen Endpunkt und die Secret-gestützten Zugangsdaten, und beschränken Sie die Inferenz-API auf AISRV. Siehe Deployment-Topologien für das getestete Helm-Beispiel, Netzwerkanforderungen, TLS-Optionen und Prüfschritte.
Die NVIDIA-Vorbereitungsschritte gelten nur für Hosts, die GPU-Workloads ausführen. Auf einem reinen CPU-Anwendungsserver für basebox sind sie nicht erforderlich.
Brauche ich Let's Encrypt für eine private Installation?
Nein. Verwenden Sie global.tls.mode=existing-secret mit einem Zertifikat Ihrer
internen CA oder global.tls.mode=local für ein selbst verwaltetes
Evaluierungszertifikat. Client-Geräte müssen der ausstellenden CA vertrauen. Siehe
Deployment-Topologien.
Kann ich das Verhalten der Support-Schaltfläche im Benutzermenü ändern?
Ja, setzen Sie VITE_BB_SUPPORT_BUTTON_LINK in der Frontend-Konfiguration. Tragen Sie die URL ein, zu der der Nutzer beim Klick weitergeleitet werden soll. Setzen Sie einen leeren String, wird die Schaltfläche ausgeblendet.
Troubleshooting
Statt einer Anmeldeseite sehe ich eine Seite „Organisation not found".
Stellen Sie sicher, dass VITE_BB_OIDC_FORCE_REALM in der Frontend-Konfiguration auf primary gesetzt ist.
Beim Zugriff auf die Anwendung sehe ich nur einen Ladekreis.
Drücken Sie F11, um die Browser-Konsole zu öffnen, und prüfen Sie das Log.
IdP/Keycloak nicht erreichbar
Suchen Sie nach Einträgen, die auf Verbindungsprobleme zu Ihrer Keycloak-Instanz hinweisen.
Ich sehe /auth/... Failed to load resource: the server responded with a status of 404 (Not Found)
Sehen Sie einen 404 im Zusammenhang mit auth, ist höchstwahrscheinlich der Pfad zu Ihrem IdP (z. B. Keycloak) falsch. Prüfen Sie die Frontend-Umgebungsvariable VITE_BB_OIDC_DOMAIN; sie muss mit einem Schrägstrich enden und in der Regel mit dem Verzeichnis realms/, z. B. https://keycloak.your-domain.de/auth/realms/.
Erhalten Sie eine JSON-Antwort auf curl -k https://localhost/auth/realms/primary/.well-known/openid-configuration (die URL muss ggf. leicht an Ihre Konfiguration angepasst werden), ist der korrekte Wert für VITE_BB_OIDC_DOMAIN „https://basebox.your-domain.de/auth/realms/" (beachten Sie den abschließenden Schrägstrich).
Nach der Anmeldung gerät die Anwendung in eine Weiterleitungsschleife.
Das bedeutet in der Regel, dass die Authentifizierung an einer unerwarteten Stelle fehlschlägt. Wir arbeiten daran, die Fehlerbehandlung hier zu verbessern.
- Löschen Sie die Browserdaten (Cookies und Local Storage) und versuchen Sie es erneut.
- Hilft das nicht, prüfen Sie die Browser-Konsole; sehen Sie INVALID_TOKEN-Fehler, prüfen Sie auch die
aisrv-Logs. Weitere Hinweise in den folgenden Fragen.
Das aisrv-Log enthält Meldungen „iss does not match".
Das deutet darauf hin, dass die Einstellung AISRV_OIDC_IDP_URL für AISRV keine Basis-URL ist oder nicht mit der Einstellung VITE_BB_OIDC_DOMAIN des Frontends übereinstimmt. Müssen diese beiden Werte tatsächlich verschieden sein, können Sie für aisrv auch die Variable AISRV_OIDC_ISSUER_URL direkt auf den erwarteten ISS-Wert setzen, wie im Log angegeben.
Hier ist jedoch Vorsicht geboten: basebox aisrv nutzt diesen Wert, um festzustellen, ob ein Access-Token, mit dem sich ein Browser verbindet, tatsächlich von der richtigen Keycloak-/IdP-Instanz ausgestellt wurde. Setzen Sie ihn auf einen fremden Aussteller, können dessen Tokens für den Zugriff auf Ihre basebox-Instanz verwendet werden.
Ich sehe die Fehlermeldung „data transmission failed (SSE)" oder ähnlich („Fehler bei der Datenübertragung")
Prüfen Sie die Browser-Konsole und vor allem die aisrv-Logs. Das Problem kann zwischen Browser und Server liegen oder zwischen aisrv und dem Inferenz-Endpunkt – oder ragsrv.
inference und ragsrv-support starten nicht: Temporary error in name resolution
Das ist ein häufiges Problem, wenn Sie den Cluster mit k3s auf Linux-Systemen mit systemd betreiben (praktisch alle, z. B. Ubuntu und Debian). Details hier. Die einfachste Lösung ist, dem coredns-Pod direkt einen DNS-Server vorzugeben; beachten Sie, dass das systemd-resolved des Hosts unter 127.0.0.53 nicht funktioniert. Steht kein DNS-Server zur Verfügung, können Sie Cloudflares 1.1.1.1 oder Googles 8.8.8.8 verwenden.
So setzen Sie den DNS-Server:
Das öffnet Ihren System-Editor (standardmäßig vi); suchen Sie die Zeile forward . /etc/resolv.conf und ersetzen Sie sie durch:
Starten Sie dann den coredns-Pod neu:
Dieses Beispiel verwendet Cloudflares DNS-Dienst mit Fallback; ersetzen Sie ihn ggf. durch Ihren DNS-Server.