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

// installation

STORESRV-Konfiguration

Gilt für

Produkt: Server · Zielgruppe: Platform Operator

Übersicht

STORESRV ist ein Speicherdienst, der eine GraphQL-API zur Verwaltung der Datenpersistenz in der basebox-KI-Anwendung bereitstellt. Er verbindet sich mit einer PostgreSQL-Datenbank und nutzt OAuth2 zur Authentifizierung. Wie AISRV ist dieser Server für den Betrieb hinter einem Reverse Proxy ausgelegt und bietet selbst keine TLS-Unterstützung.

Deployment

STORESRV wird per Helm-Chart in Kubernetes-Cluster bereitgestellt, mit einer integrierten, von CloudNativePG verwalteten PostgreSQL-Datenbank.

Helm-Chart-Konfiguration

Grundeinstellungen

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

Dienstkonfiguration

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

Ressourcenverwaltung

Parameter	Beschreibung
`resources.requests`	CPU-/Speicher-Requests
`resources.limits`	CPU-/Speicher-Limits
`autoscaling.enabled`	Horizontales Pod-Autoscaling aktivieren
`autoscaling.minReplicas`	Minimale Anzahl Replikate
`autoscaling.maxReplicas`	Maximale Anzahl Replikate
`autoscaling.targetCPUUtilizationPercentage`	Ziel-CPU für die Skalierung

Health-Checks

Parameter	Beschreibung
`livenessProbe`	Konfiguration der Liveness-Probe
`readinessProbe`	Konfiguration der Readiness-Probe

Datenbankkonfiguration

Datenbankeinstellungen

Parameter	Standard	Beschreibung
`database.enabled`	`true`	Datenbankerstellung aktivieren
`database.imageName`	`ghcr.io/cloudnative-pg/postgresql:16-standard-bookworm`	PostgreSQL-Image
`database.host`	`storesrv-db-rw`	Datenbank-Host (Read-Write-Service)
`database.port`	`5432`	Datenbank-Port
`database.user`	`storesrv`	Datenbank-Benutzername
`database.password`	`<secure-password>`	Datenbank-Passwort
`database.name`	`storesrv`	Datenbankname
`database.sslMode`	`disable`	SSL-Modus der Datenbank

CloudNativePG-Cluster-Einstellungen

Parameter	Standard	Beschreibung
`storesrv-db.cluster.instances`	`1`	Anzahl PostgreSQL-Instanzen
`storesrv-db.cluster.storage.size`	`10Gi`	Speichergröße der Datenbank
`storesrv-db.cluster.storage.storageClass`	`default`	Zu verwendende Storage Class
`storesrv-db.cluster.monitoring.enablePodMonitor`	`false`	Prometheus-Monitoring aktivieren

Migrationseinstellungen

Variable	Standard	Beschreibung
`STORESRV_DB_MIGRATE`	`false`	Automatische Datenbankmigration beim Start
`STORESRV_DB_MIGRATE_BACKUP`	`false`	Datenbank vor Migrationen sichern
`STORESRV_DB_MIGRATE_BACKUP_DIR`	`migrations-backups`	Pfad des Backup-Verzeichnisses
`STORESRV_DB_MIGRATE_RUN_ONLY`	`false`	Nur Migrationen ausführen, dann beenden

Umgebungsvariablen

Serverkonfiguration

Variable	Standard	Beschreibung
`STORESRV_HOST`	`localhost`	Host oder IP-Adresse, auf der gelauscht wird
`STORESRV_PORT`	`8889`	Port, auf dem gelauscht wird
`STORESRV_LOG_LEVEL`	`info`	Log-Level (`trace`, `debug`, `info`, `warn`, `error`)
`STORESRV_DEBUG_MODE`	`false`	Debug-Modus: mehr Tracing
`STORESRV_ON_PREMISE`	`false`	Server-Deployment-Modus (basebox Server)

Datenbankverbindung (aus Secrets)

Variable	Quelle	Beschreibung
`STORESRV_DB_HOST`	Secret `storesrv-database`	Datenbank-Hostname
`STORESRV_DB_PORT`	Secret `storesrv-database`	Datenbank-Port
`STORESRV_DB_USER`	Secret `storesrv-database`	Datenbank-Benutzername
`STORESRV_DB_PASSWORD`	Secret `storesrv-database`	Datenbank-Passwort
`STORESRV_DB_NAME`	Secret `storesrv-database`	Datenbankname
`STORESRV_DB_SSL_MODE`	Konfiguration	SSL-Modus für die Datenbankverbindung

OAuth2-Konfiguration

Variable	Beschreibung
`STORESRV_OAUTH_IDP_URL`	Basis-URL des OAuth-Identitätsanbieters
`STORESRV_OAUTH_AUD`	OAuth2-Audience-Feld

Hinweis: Beide OAuth2-Parameter müssen gemeinsam konfiguriert werden.

GraphQL-Konfiguration

Variable	Standard	Beschreibung
`STORESRV_QUERY_DEPTH_LIMIT`	`6`	Tiefenlimit für GraphQL-Queries
`STORESRV_QUERY_COMPLEXITY_LIMIT`	`20`	Komplexitätslimit für GraphQL-Queries
`STORESRV_GRAPHQL_ALLOW_INTROSPECTION`	`false`	Introspektions-Queries erlauben
`STORESRV_GRAPHQL_APOLLO_TRACING`	`false`	Apollo-Tracing aktivieren
`STORESRV_GRAPHQL_GRAPHIQL`	`false`	GraphiQL-Oberfläche aktivieren

Konfigurationsbeispiele

Produktivkonfiguration

# values-production.yaml
replicaCount: 1

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

service:
  type: ClusterIP
  port: 8889

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

resources:
  requests:
    cpu: 500m
    memory: 1Gi
  limits:
    cpu: 1000m
    memory: 2Gi

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

livenessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 15
  periodSeconds: 5

database:
  enabled: true
  host: storesrv-db-rw
  port: 5432
  user: storesrv
  password: "<generate-secure-password>"
  name: storesrv
  sslMode: "require"

storesrv-db:
  cluster:
    instances: 3
    storage:
      size: 50Gi
      storageClass: fast-ssd
    monitoring:
      enablePodMonitor: true

env:
  # Server
  STORESRV_HOST: "0.0.0.0"
  STORESRV_PORT: "8889"
  STORESRV_LOG_LEVEL: "info"
  STORESRV_DEBUG_MODE: "false"

  # Database (from secrets)
  STORESRV_DB_HOST:
    valueFrom:
      secretKeyRef:
        name: storesrv-database
        key: host
  STORESRV_DB_PORT:
    valueFrom:
      secretKeyRef:
        name: storesrv-database
        key: port
  STORESRV_DB_USER:
    valueFrom:
      secretKeyRef:
        name: storesrv-database
        key: username
  STORESRV_DB_PASSWORD:
    valueFrom:
      secretKeyRef:
        name: storesrv-database
        key: password
  STORESRV_DB_NAME:
    valueFrom:
      secretKeyRef:
        name: storesrv-database
        key: name
  STORESRV_DB_SSL_MODE: "require"

  # Migrations
  STORESRV_DB_MIGRATE: "true"
  STORESRV_DB_MIGRATE_BACKUP: "true"
  STORESRV_DB_MIGRATE_BACKUP_DIR: "/backups"

  # OAuth2
  STORESRV_OAUTH_IDP_URL: "http://idp:8080"
  STORESRV_OAUTH_AUD: "storesrv"

  # GraphQL
  STORESRV_QUERY_DEPTH_LIMIT: "8"
  STORESRV_QUERY_COMPLEXITY_LIMIT: "50"
  STORESRV_GRAPHQL_ALLOW_INTROSPECTION: "false"
  STORESRV_GRAPHQL_GRAPHIQL: "false"

Installation

Voraussetzungen

Kubernetes-Cluster (1.23+)
Helm 3.x
CloudNativePG-Operator installiert
Storage-Provisioner
OAuth2-/OIDC-Provider konfiguriert

CloudNativePG-Operator installieren

helm repo add cnpg https://cloudnative-pg.github.io/charts
helm upgrade --install cnpg \
  --namespace cnpg-system \
  --create-namespace \
  cnpg/cloudnative-pg

STORESRV installieren

# Install with custom values
helm install storesrv oci://gitea.basebox.health/basebox-distribution/helm/storesrv \
  --values values-production.yaml \
  --namespace basebox \
  --create-namespace

# Verify installation
kubectl get pods -n basebox -l app.kubernetes.io/name=storesrv
kubectl get cluster -n basebox storesrv-db

Upgrade

helm upgrade storesrv oci://gitea.basebox.health/basebox-distribution/helm/storesrv \
  --values values-production.yaml \
  --namespace basebox

Deinstallation

helm uninstall storesrv --namespace basebox

# Delete PVCs if needed
kubectl delete pvc -n basebox -l cnpg.io/cluster=storesrv-db

Migrationen

Wie Migrationen funktionieren

Migrationsverfolgung: Die Tabelle _migrations_history verfolgt angewendete Migrationen
Nummeriertes Format: Vnnn__<migration_name> (doppelte Unterstriche)
Sequenzielle Ausführung: Migrationen laufen in numerischer Reihenfolge
Prüfsummenvalidierung: Erkennt Änderungen an Migrationsdateien
Eingebettet: Alle Migrationen sind in die Anwendungs-Binary eingebettet

Migrationen ausführen

Automatisch beim Start:

env:
  STORESRV_DB_MIGRATE: "true"
  STORESRV_DB_MIGRATE_BACKUP: "true"

Nur Migrationen (kein Serverstart):

env:
  STORESRV_DB_MIGRATE: "true"
  STORESRV_DB_MIGRATE_RUN_ONLY: "true"

Prüfung

Deployment prüfen

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

# Check database
kubectl get cluster -n basebox storesrv-db

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

GraphQL-API testen

# Port forward
kubectl port-forward -n basebox svc/storesrv 8889:8889

# Test query
curl -X POST http://localhost:8889/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __typename }"}'

Integration mit anderen Diensten

IDP (Keycloak)

STORESRV nutzt OAuth2 zur Authentifizierung über den IDP:

env:
  STORESRV_OAUTH_IDP_URL: "http://idp:8080"
  STORESRV_OAUTH_AUD: "storesrv"

AISRV

AISRV verbindet sich für Speicheroperationen mit STORESRV:

# In AISRV configuration
env:
  AISRV_STORE_URL: "http://storesrv:8889"

Performance-Tuning

Ressourcenzuteilung

resources:
  requests:
    cpu: 500m
    memory: 1Gi
  limits:
    cpu: 1000m
    memory: 2Gi

Monitoring

Datenbank-Monitoring

CloudNativePG-Monitoring aktivieren:

storesrv-db:
  cluster:
    monitoring:
      enablePodMonitor: true