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

// installation

STORESRV Configuration

Applies to

Product: Server · Audience: Platform Operator

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://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

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