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

STORESRV Configuration

Overview

STORESRV is a storage service that provides a GraphQL API for managing data persistence in the basebox AI application. It connects to a PostgreSQL database and uses OAuth2 for authentication. Like AISRV, this server is designed to run behind a reverse proxy and does not provide TLS support on its own.

Deployment

STORESRV is deployed via Helm chart to Kubernetes clusters with an integrated PostgreSQL database managed by CloudNativePG.

Helm Chart Configuration

Basic Settings

Parameter Default Description
replicaCount 1 Number of STORESRV pod replicas
image.repository gitea.basebox.health/basebox-distribution/storesrv Container image repository
image.pullPolicy IfNotPresent Image pull policy
image.tag latest Image tag to deploy
fullnameOverride storesrv Override the full name of the deployment

Service Configuration

Parameter Default Description
service.type ClusterIP Kubernetes service type
service.port 8889 Service port

Resource Management

Parameter Description
resources.requests CPU/memory resource requests
resources.limits CPU/memory resource limits
autoscaling.enabled Enable horizontal pod autoscaling
autoscaling.minReplicas Minimum number of replicas
autoscaling.maxReplicas Maximum number of replicas
autoscaling.targetCPUUtilizationPercentage Target CPU for scaling

Health Checks

Parameter Description
livenessProbe Liveness probe configuration
readinessProbe Readiness probe configuration

Database Configuration

Database Settings

Parameter Default Description
database.enabled true Enable database creation
database.imageName ghcr.io/cloudnative-pg/postgresql:16-standard-bookworm PostgreSQL image
database.host storesrv-db-rw Database host (read-write service)
database.port 5432 Database port
database.user storesrv Database username
database.password <secure-password> Database password
database.name storesrv Database name
database.sslMode disable Database SSL mode

CloudNativePG Cluster Settings

Parameter Default Description
storesrv-db.cluster.instances 1 Number of PostgreSQL instances
storesrv-db.cluster.storage.size 10Gi Storage size for database
storesrv-db.cluster.storage.storageClass default Storage class to use
storesrv-db.cluster.monitoring.enablePodMonitor false Enable Prometheus monitoring

Migration Settings

Variable Default Description
STORESRV_DB_MIGRATE false Automatic database migration on startup
STORESRV_DB_MIGRATE_BACKUP false Backup database before migrations
STORESRV_DB_MIGRATE_BACKUP_DIR migrations-backups Backup directory path
STORESRV_DB_MIGRATE_RUN_ONLY false Run only migrations then exit

Environment Variables

Server Configuration

Variable Default Description
STORESRV_HOST localhost Host or IP address to listen on
STORESRV_PORT 8889 Port to listen on
STORESRV_LOG_LEVEL info Log level (trace, debug, info, warn, error)
STORESRV_DEBUG_MODE false Debug mode: enables more tracing
STORESRV_ON_PREMISE false On-premise deployment mode

Database Connection (from Secrets)

Variable Source Description
STORESRV_DB_HOST storesrv-database secret Database hostname
STORESRV_DB_PORT storesrv-database secret Database port
STORESRV_DB_USER storesrv-database secret Database username
STORESRV_DB_PASSWORD storesrv-database secret Database password
STORESRV_DB_NAME storesrv-database secret Database name
STORESRV_DB_SSL_MODE Configuration SSL mode for database connection

OAuth2 Configuration

Variable Description
STORESRV_OAUTH_IDP_URL Base URL of OAuth Identity Provider
STORESRV_OAUTH_AUD OAuth2 audience field

Note: Both OAuth2 parameters must be configured together.

GraphQL Configuration

Variable Default Description
STORESRV_QUERY_DEPTH_LIMIT 6 GraphQL query depth limit
STORESRV_QUERY_COMPLEXITY_LIMIT 20 GraphQL query complexity limit
STORESRV_GRAPHQL_ALLOW_INTROSPECTION false Allow introspection queries
STORESRV_GRAPHQL_APOLLO_TRACING false Enable Apollo tracing
STORESRV_GRAPHQL_GRAPHIQL false Enable GraphiQL interface

Configuration Examples

Production Configuration

# 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

Prerequisites

  • Kubernetes cluster (1.23+)
  • Helm 3.x
  • CloudNativePG operator installed
  • Storage provisioner
  • OAuth2/OIDC provider configured

Install CloudNativePG Operator

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

Install STORESRV

# Install with custom values
helm install storesrv oci://hub.basebox.ai/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://hub.basebox.ai/helm/storesrv \
  --values values-production.yaml \
  --namespace basebox

Uninstall

helm uninstall storesrv --namespace basebox

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

Migrations

How Migrations Work

  • Migration Tracking: _migrations_history table tracks applied migrations
  • Numbered Format: Vnnn__<migration_name> (double underscores)
  • Sequential Execution: Migrations run in numerical order
  • Checksum Validation: Detects alterations to migration files
  • Embedded: All migrations embedded in application binary

Running Migrations

Automatic on Startup: 

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

Migrations Only (No Server Start): 

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

Verification

Check Deployment

# 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

Test GraphQL API

# 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 with Other Services

IDP (Keycloak)

STORESRV uses OAuth2 for authentication via IDP:

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

AISRV

AISRV connects to STORESRV for storage operations:

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

Performance Tuning

Resource Allocation

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

Monitoring

Database Monitoring

Enable CloudNativePG monitoring:

storesrv-db:
  cluster:
    monitoring:
      enablePodMonitor: true