Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// installation

basebox-Frontend-Konfiguration

Gilt für

Produkt: Server · Zielgruppe: Platform Operator

Übersicht

Das basebox-Frontend ist eine Vue-3-Single-Page-Application (SPA), die die Benutzeroberfläche der basebox-KI-Plattform bereitstellt. Es kommuniziert über GraphQL mit den Backend-Diensten und nutzt OpenID Connect (OIDC) zur Authentifizierung.

Deployment

Das Frontend wird per Helm-Chart in Kubernetes-Cluster bereitgestellt.

Helm-Chart-Konfiguration

Grundeinstellungen

Parameter	Standard	Beschreibung
`replicaCount`	`1`	Anzahl der Frontend-Pod-Replikate
`image.repository`	`gitea.basebox.health/basebox-distribution/frontend`	Container-Image-Repository
`image.pullPolicy`	`Always`	Image-Pull-Policy (`Always`, `IfNotPresent`, `Never`)
`image.tag`	`latest`	Auszurollender Image-Tag
`fullnameOverride`	`frontend`	Vollständigen Namen des Deployments überschreiben

Dienstkonfiguration

Parameter	Standard	Beschreibung
`service.type`	`ClusterIP`	Kubernetes-Service-Typ
`service.port`	`3000`	Service-Port

Ingress-Konfiguration

Parameter	Standard	Beschreibung
`ingress.enabled`	`false`	Ingress-Ressource aktivieren
`ingress.className`	`""`	Name der Ingress-Klasse
`ingress.annotations`	`{}`	Ingress-Annotationen
`ingress.hosts`	`[]`	Liste der Ingress-Hosts
`ingress.tls`	`[]`	TLS-Konfiguration für den Ingress

HTTPRoute-Konfiguration (Gateway API)

Parameter	Standard	Beschreibung
`httpRoute.enabled`	`false`	Gateway-API-HTTPRoute aktivieren
`httpRoute.parentRefs`	`[{name: gateway, sectionName: http}]`	Gateway-Referenzen
`httpRoute.hostnames`	`[]`	Hostnamen für die Route
`httpRoute.rules`	`[]`	Routing-Regeln und Filter

Ressourcenverwaltung

Parameter	Standard	Beschreibung
`resources`	`{}`	CPU-/Speicher-Requests und -Limits
`autoscaling.enabled`	`false`	Horizontales Pod-Autoscaling aktivieren
`autoscaling.minReplicas`	`1`	Minimale Anzahl Replikate
`autoscaling.maxReplicas`	`100`	Maximale Anzahl Replikate
`autoscaling.targetCPUUtilizationPercentage`	`80`	Ziel-CPU-Auslastung für die Skalierung

Health-Checks

Parameter	Standard	Beschreibung
`livenessProbe.httpGet.path`	`/`	Pfad der Liveness-Probe
`livenessProbe.httpGet.port`	`http`	Port der Liveness-Probe
`readinessProbe.httpGet.path`	`/`	Pfad der Readiness-Probe
`readinessProbe.httpGet.port`	`http`	Port der Readiness-Probe

Umgebungsvariablen

Umgebungsvariablen werden im Abschnitt env der Helm-Values-Datei konfiguriert. Diese Variablen werden zur Build-Zeit in die Anwendung eingebettet.

Erforderliche Umgebungsvariablen

Variable	Beschreibung	Beispiel
`VITE_BB_GRAPHQL_URL`	URL des GraphQL-API-Endpunkts	`{{ .Values.publicAddress }}/graphql`
`VITE_BB_OIDC_DOMAIN`	Basis-URL des OIDC-Providers mit Realms-Pfad. Muss mit Schrägstrich enden	`{{ .Values.publicAddress }}/auth/realms/`
`publicAddress`	Öffentliche Basis-URL der Anwendung	`https://basebox.your-company.com`

Optionale Umgebungsvariablen

Variable	Standard	Beschreibung
`VITE_BB_OIDC_FORCE_REALM`	Keiner	Einen bestimmten OIDC-Realm erzwingen (z. B. `primary`)
`VITE_BB_OIDC_CLIENT_ID`	`aiclient`	OIDC-Client-ID
`VITE_BB_OIDC_SCOPES`	`openid profile email offline_access`	Anzufordernde OAuth2-Scopes
`VITE_BB_RAG_SUPPORTED_FILE_TYPES`	Keiner	Kommagetrennte Dateitypen für RAG (z. B. `pdf,docx,txt`)
`VITE_BB_SUPPORT_BUTTON_LINK`	Erstellt Support-Ticket	Eigene Support-URL oder leerer String zum Ausblenden
`VITE_BB_ENABLE_TRANSLATION_APP`	`true`	Eingebaute Übersetzungs-App ein-/ausblenden
`VITE_BB_POSTHOG_KEY`	Keiner	Posthog-Analytics-API-Schlüssel
`APP_TRUST_PROXY`	`false`	Proxy-Header vertrauen (hinter Reverse Proxy auf `true` setzen)
`APP_SIGNUP_REALM`	Keiner	OIDC-Realm für die Benutzerregistrierung

Konfigurationsbeispiele

Minimale Konfiguration

# values.yaml
publicAddress: "https://basebox.company.com"

env:
  VITE_BB_OIDC_DOMAIN: "{{ .Values.publicAddress }}/auth/realms/"
  VITE_BB_GRAPHQL_URL: "{{ .Values.publicAddress }}/graphql"
  VITE_BB_OIDC_FORCE_REALM: primary
  APP_TRUST_PROXY: "true"

Produktivkonfiguration

# values-production.yaml
replicaCount: 3

image:
  repository: gitea.basebox.health/basebox-distribution/frontend
  tag: "v1.2.3"
  pullPolicy: IfNotPresent

publicAddress: "https://basebox.company.com"

service:
  type: ClusterIP
  port: 3000

ingress:
  enabled: true
  className: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
  hosts:
    - host: basebox.company.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: basebox-tls
      hosts:
        - basebox.company.com

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 100m
    memory: 128Mi

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

env:
  VITE_BB_OIDC_DOMAIN: "{{ .Values.publicAddress }}/auth/realms/"
  VITE_BB_GRAPHQL_URL: "{{ .Values.publicAddress }}/graphql"
  VITE_BB_OIDC_FORCE_REALM: production
  VITE_BB_RAG_SUPPORTED_FILE_TYPES: "pdf,docx,txt,md,csv,xlsx"
  VITE_BB_POSTHOG_KEY: "phc_your_production_key"
  VITE_BB_SUPPORT_BUTTON_LINK: "https://support.company.com"
  APP_TRUST_PROXY: "true"
  APP_SIGNUP_REALM: signup

Gateway-API-Konfiguration

Für Umgebungen mit Gateway API statt Ingress:

# values-gateway.yaml
publicAddress: "https://basebox.company.com"

httpRoute:
  enabled: true
  annotations:
    example.com/annotation: "value"
  parentRefs:
    - name: company-gateway
      namespace: gateway-system
      sectionName: https
  hostnames:
    - basebox.company.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /

env:
  VITE_BB_OIDC_DOMAIN: "{{ .Values.publicAddress }}/auth/realms/"
  VITE_BB_GRAPHQL_URL: "{{ .Values.publicAddress }}/graphql"
  VITE_BB_OIDC_FORCE_REALM: primary
  APP_TRUST_PROXY: "true"

Installation

Voraussetzungen

Kubernetes-Cluster (1.19+)
Helm 3.x
kubectl für den Zugriff auf Ihren Cluster konfiguriert
Zugang zur Container-Registry (bei privaten Images)

Chart installieren

# Add the Helm repository (if applicable)
helm repo add basebox https://charts.basebox.health
helm repo update

# Install with default values
helm install frontend basebox/frontend

# Install with custom values
helm install frontend basebox/frontend \
  --values values-production.yaml \
  --namespace basebox \
  --create-namespace

# Install with specific values via command line
helm install frontend basebox/frontend \
  --set publicAddress=https://basebox.company.com \
  --set replicaCount=3 \
  --namespace basebox

Chart aktualisieren

# Upgrade with new values
helm upgrade frontend basebox/frontend \
  --values values-production.yaml \
  --namespace basebox

# Upgrade to specific version
helm upgrade frontend basebox/frontend \
  --version 1.2.3 \
  --namespace basebox

Chart deinstallieren

helm uninstall frontend --namespace basebox

Prüfung

Deployment-Status prüfen

# Check pods
kubectl get pods -n basebox -l app.kubernetes.io/name=frontend

# Check service
kubectl get svc -n basebox -l app.kubernetes.io/name=frontend

# Check ingress
kubectl get ingress -n basebox

# View logs
kubectl logs -n basebox -l app.kubernetes.io/name=frontend --tail=100

Konfiguration prüfen

# Check environment variables in running pod
kubectl exec -n basebox deployment/frontend -- env | grep VITE_BB

# Describe pod to see configuration
kubectl describe pod -n basebox -l app.kubernetes.io/name=frontend

Troubleshooting

Pod startet nicht

# Check pod status
kubectl get pods -n basebox -l app.kubernetes.io/name=frontend

# View pod events
kubectl describe pod -n basebox <pod-name>

# Check logs
kubectl logs -n basebox <pod-name>

Häufige Probleme: - Fehlschlagende Liveness-/Readiness-Probes: Probe-Konfiguration und Anwendungsgesundheit prüfen - Ressourcenlimits: Sicherstellen, dass der Cluster ausreichende Ressourcen hat

OIDC-Authentifizierung schlägt fehl

Symptome: Nutzer können sich nicht anmelden, Weiterleitungsschleifen, Token-Fehler

Lösungen: - Prüfen, dass VITE_BB_OIDC_DOMAIN mit Schrägstrich endet - Bestätigen, dass publicAddress korrekt und erreichbar ist - Prüfen, dass die OIDC-Realm-Konfiguration zu VITE_BB_OIDC_FORCE_REALM passt - Sicherstellen, dass der OIDC-Provider aus den Browsern der Nutzer erreichbar ist

GraphQL-Verbindungsprobleme

Symptome: API-Aufrufe scheitern, leere Seiten, Konsolenfehler

Lösungen: - Prüfen, dass VITE_BB_GRAPHQL_URL auf ein erreichbares Backend zeigt - Ingress-/Service-Konfiguration der Backend-Dienste prüfen - Bestätigen, dass CORS-Header im Backend korrekt konfiguriert sind - Backend-Erreichbarkeit testen: curl -I https://basebox.company.com/graphql

Ingress funktioniert nicht

Symptome: Anwendung über die Domain nicht erreichbar

Lösungen: - Prüfen, dass der Ingress-Controller installiert ist und läuft - Ingress-Ressource prüfen: kubectl get ingress -n basebox - Bestätigen, dass DNS auf IP/Hostname des Ingress-Controllers zeigt - Logs des Ingress-Controllers auf Fehler prüfen - Gültigkeit der TLS-Zertifikate prüfen (bei HTTPS)

Sicherheits-Header

Stellen Sie sicher, dass Ihr Ingress-Controller oder Reverse Proxy Sicherheits-Header setzt: - X-Frame-Options: SAMEORIGIN - X-Content-Type-Options: nosniff - X-XSS-Protection: 1; mode=block - Referrer-Policy: strict-origin-when-cross-origin

Performance-Tuning

Ressourcenzuteilung

Nach Ihrer Last anpassen:

resources:
  requests:
    cpu: 100m      # Minimum CPU
    memory: 128Mi  # Minimum memory
  limits:
    cpu: 500m      # Maximum CPU
    memory: 512Mi  # Maximum memory

Horizontales Pod-Autoscaling

Autoscaling für Umgebungen mit hohem Verkehr aktivieren:

autoscaling:
  enabled: true
  minReplicas: 1
  maxReplicas: 3
  targetCPUUtilizationPercentage: 70
  # Optional: Memory-based scaling
  # targetMemoryUtilizationPercentage: 80

Monitoring

Health-Checks

Die Anwendung stellt Health-Endpunkte für Kubernetes-Probes bereit: - Liveness-Probe: GET / – Prüft, ob die Anwendung läuft - Readiness-Probe: GET / – Prüft, ob die Anwendung bereit ist, Verkehr zu bedienen

Metriken

Ist Posthog konfiguriert (VITE_BB_POSTHOG_KEY), werden Nutzungsdaten erhoben: - Seitenaufrufe - Nutzerinteraktionen - Fehlerverfolgung

Logging

Anwendungslogs anzeigen:

# Stream logs
kubectl logs -n basebox -l app.kubernetes.io/name=frontend --follow

# View recent logs
kubectl logs -n basebox -l app.kubernetes.io/name=frontend --tail=100

# Logs from specific pod
kubectl logs -n basebox <pod-name>