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

Basebox Frontend Configuration

Overview

The basebox frontend is a Vue 3 single-page application (SPA) that provides the user interface for the basebox AI platform. It communicates with backend services via GraphQL and uses OpenID Connect (OIDC) for authentication.

Deployment

The frontend is deployed via Helm chart to Kubernetes clusters.

Helm Chart Configuration

Basic Settings

Parameter	Default	Description
`replicaCount`	`1`	Number of frontend pod replicas
`image.repository`	`gitea.basebox.health/basebox-distribution/frontend`	Container image repository
`image.pullPolicy`	`Always`	Image pull policy (`Always`, `IfNotPresent`, `Never`)
`image.tag`	`latest`	Image tag to deploy
`fullnameOverride`	`frontend`	Override the full name of the deployment

Service Configuration

Parameter	Default	Description
`service.type`	`ClusterIP`	Kubernetes service type
`service.port`	`3000`	Service port

Ingress Configuration

Parameter	Default	Description
`ingress.enabled`	`false`	Enable ingress resource
`ingress.className`	`""`	Ingress class name
`ingress.annotations`	`{}`	Ingress annotations
`ingress.hosts`	`[]`	List of ingress hosts
`ingress.tls`	`[]`	TLS configuration for ingress

HTTPRoute Configuration (Gateway API)

Parameter	Default	Description
`httpRoute.enabled`	`false`	Enable Gateway API HTTPRoute
`httpRoute.parentRefs`	`[{name: gateway, sectionName: http}]`	Gateway references
`httpRoute.hostnames`	`[]`	Hostnames for the route
`httpRoute.rules`	`[]`	Routing rules and filters

Resource Management

Parameter	Default	Description
`resources`	`{}`	CPU/memory resource requests and limits
`autoscaling.enabled`	`false`	Enable horizontal pod autoscaling
`autoscaling.minReplicas`	`1`	Minimum number of replicas
`autoscaling.maxReplicas`	`100`	Maximum number of replicas
`autoscaling.targetCPUUtilizationPercentage`	`80`	Target CPU utilization for scaling

Health Checks

Parameter	Default	Description
`livenessProbe.httpGet.path`	`/`	Liveness probe path
`livenessProbe.httpGet.port`	`http`	Liveness probe port
`readinessProbe.httpGet.path`	`/`	Readiness probe path
`readinessProbe.httpGet.port`	`http`	Readiness probe port

Environment Variables

Environment variables are configured in the env section of the Helm values file. These variables are embedded into the application at build time.

Required Environment Variables

Variable	Description	Example
`VITE_BB_GRAPHQL_URL`	URL of the GraphQL API endpoint	`{{ .Values.publicAddress }}/graphql`
`VITE_BB_OIDC_DOMAIN`	Base URL of OIDC provider with realms path. Must have trailing slash	`{{ .Values.publicAddress }}/auth/realms/`
`publicAddress`	Public-facing base URL of the application	`https://basebox.your-company.com`

Optional Environment Variables

Variable	Default	Description
`VITE_BB_OIDC_FORCE_REALM`	None	Force a specific OIDC realm (e.g., `primary`)
`VITE_BB_OIDC_CLIENT_ID`	`aiclient`	OIDC client ID
`VITE_BB_OIDC_SCOPES`	`openid profile email offline_access`	OAuth2 scopes to request
`VITE_BB_RAG_SUPPORTED_FILE_TYPES`	None	Comma-separated file types for RAG (e.g., `pdf,docx,txt`)
`VITE_BB_SUPPORT_BUTTON_LINK`	Creates support ticket	Custom support URL or empty string to hide
`VITE_BB_ENABLE_TRANSLATION_APP`	`true`	Show/hide built-in translation app
`VITE_BB_POSTHOG_KEY`	None	Posthog analytics API key
`APP_TRUST_PROXY`	`false`	Trust proxy headers (set to `true` behind reverse proxy)
`APP_SIGNUP_REALM`	None	OIDC realm for user signup

Configuration Examples

Minimal Configuration

# 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"

Production Configuration

# 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 Configuration

For environments using Gateway API instead of 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

Prerequisites

Kubernetes cluster (1.19+)
Helm 3.x
kubectl configured to access your cluster
Container registry access (if using private images)

Install the Chart

# 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

Upgrade the Chart

# 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

Uninstall the Chart

helm uninstall frontend --namespace basebox

Verification

Check Deployment Status

# 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

Verify Configuration

# 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 Not Starting

# 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>

Common Issues: - Liveness/readiness probe failures: Check probe configuration and application health - Resource limits: Ensure cluster has sufficient resources

OIDC Authentication Failures

Symptoms: Users cannot log in, redirect loops, token errors

Solutions: - Verify VITE_BB_OIDC_DOMAIN has trailing slash - Confirm publicAddress is correct and accessible - Check OIDC realm configuration matches VITE_BB_OIDC_FORCE_REALM - Ensure OIDC provider is accessible from user browsers

GraphQL Connection Issues

Symptoms: API calls fail, blank pages, console errors

Solutions: - Verify VITE_BB_GRAPHQL_URL points to accessible backend - Check ingress/service configuration for backend services - Confirm CORS headers are properly configured on backend - Test backend connectivity: curl -I https://basebox.company.com/graphql

Ingress Not Working

Symptoms: Cannot access application via domain

Solutions: - Verify ingress controller is installed and running - Check ingress resource: kubectl get ingress -n basebox - Confirm DNS points to ingress controller IP/hostname - Review ingress controller logs for errors - Verify TLS certificates are valid (if using HTTPS)

Security Headers

Ensure your ingress controller or reverse proxy adds security headers: - X-Frame-Options: SAMEORIGIN - X-Content-Type-Options: nosniff - X-XSS-Protection: 1; mode=block - Referrer-Policy: strict-origin-when-cross-origin

Performance Tuning

Resource Allocation

Adjust based on your workload:

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

Horizontal Pod Autoscaling

Enable autoscaling for high-traffic environments:

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

Monitoring

Health Checks

The application exposes health endpoints used by Kubernetes probes: - Liveness Probe: GET / - Checks if application is running - Readiness Probe: GET / - Checks if application is ready to serve traffic

Metrics

If Posthog is configured (VITE_BB_POSTHOG_KEY), user analytics are collected: - Page views - User interactions - Error tracking

Logging

View application logs:

# 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>