@r8s/open-webui 0.2.0

package/__tests__/open-webui.test.ts

@@ -0,0 +1,457 @@
+import { describe, it, expect } from 'vitest'
+import { render, jsx } from '@r8s/core'
+import { OperatorContext, SecretContext, RoutingContext } from '@r8s/core/defaults'
+import { runGuardrails, noPlaintextSecrets, validateResource } from '@r8s/core'
+import { operators } from '@r8s/crds'
+import type { r8sElement } from '@r8s/core'
+
+// Open WebUI recipe tests:
+//   1. Operator declarations (cnpg via Database, redis, deduped via OperatorContext)
+//   2. Rendering: defaults incl. uploads PVC, all props, gateway/ingress adaptation
+//   3. Env wiring: upstream env names, no duplicate env names, probes, offline mode
+//   4. Security: no plaintext credentials in rendered output
+import { OpenWebui } from '../src/index'
+
+/** Render OpenWebui inside a Platform-like secrets backend (OpenBao). */
+function renderOpenWebui(props: Record<string, unknown>): ReturnType<typeof render> {
+  return render(
+    jsx(SecretContext.Provider, {
+      value: { backend: 'openbao', mount: 'kv', path: 'test' },
+      children: jsx(OpenWebui, props as never),
+    })
+  )
+}
+
+/** Render OpenWebui wrapped only in an OperatorContext (no secrets backend). */
+function renderOpenWebuiWithContext(operators_: any[], props: Record<string, unknown>): r8sElement {
+  return jsx(OperatorContext.Provider, {
+    value: operators_,
+    children: jsx(OpenWebui, props as never),
+  })
+}
+
+/**
+ * k8s rejects duplicate env names in one container — assert every env
+ * list we render is unique.
+ */
+function assertUniqueEnvNames(env: Array<{ name: string }>): void {
+  const names = env.map((e) => e.name)
+  const dupes = names.filter((n, i) => names.indexOf(n) !== i)
+  expect(dupes).toEqual([])
+  expect(new Set(names).size).toBe(names.length)
+}
+
+const openbao = { backend: 'openbao', mount: 'kv', path: 'test' }
+
+describe('operator declarations', () => {
+  it('declares the cnpg operator via the Database recipe', () => {
+    const result = renderOpenWebui({ host: 'chat.example.com' })
+    expect(result.operators.some((op) => op.name === 'cnpg')).toBe(true)
+  })
+
+  it('declares the redis operator when cache is enabled', () => {
+    const result = renderOpenWebui({ host: 'chat.example.com', cache: true })
+    expect(result.operators.some((op) => op.name === 'redis-operator')).toBe(true)
+  })
+
+  it('does not declare operators when cache is off (default)', () => {
+    const result = render(
+      jsx(OpenWebui, { host: 'chat.example.com', secretsName: 'existing-secrets' })
+    )
+    const names = result.operators.map((op) => op.name)
+    expect(names).toContain('cnpg')
+    expect(names).not.toContain('redis-operator')
+  })
+
+  it('deduplicates operators provided via context', () => {
+    const result = render(
+      renderOpenWebuiWithContext([operators['redis-operator'](), operators['cnpg']()], {
+        host: 'chat.example.com',
+        cache: true,
+        secretsName: 'existing-secrets',
+      })
+    )
+    const names = result.operators.map((op) => op.name)
+    expect(names.filter((n) => n === 'redis-operator')).toHaveLength(1)
+    expect(names.filter((n) => n === 'cnpg')).toHaveLength(1)
+  })
+
+  it('allows version overrides through context operators', () => {
+    const result = render(
+      renderOpenWebuiWithContext([operators['redis-operator']('1.0.0')], {
+        host: 'chat.example.com',
+        cache: true,
+        secretsName: 'existing-secrets',
+      })
+    )
+    const redis = result.operators.filter((op) => op.name === 'redis-operator')
+    expect(redis).toHaveLength(1)
+    expect(redis[0].version).toBe('1.0.0')
+  })
+})
+
+describe('rendering defaults', () => {
+  it('renders deployment, service, uploads PVC, database and endpoint', () => {
+    const result = renderOpenWebui({ host: 'chat.example.com', storage: '10Gi' })
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('Deployment')
+    expect(kinds).toContain('Service')
+    expect(kinds).toContain('Ingress')
+    expect(kinds).toContain('Cluster')
+    expect(kinds).toContain('PersistentVolumeClaim')
+
+    const pvc = result.resources.find(
+      (r) => r.kind === 'PersistentVolumeClaim' && (r as any).metadata.name === 'open-webui-uploads'
+    ) as any
+    expect(pvc.spec.accessModes).toEqual(['ReadWriteOnce'])
+    expect(pvc.spec.resources.requests.storage).toBe('10Gi')
+  })
+
+  it('wires the deployment image, port, probes and PVC mount', () => {
+    const result = renderOpenWebui({ host: 'chat.example.com', storage: '10Gi' })
+    const app = result.resources.find(
+      (r) => r.kind === 'Deployment' && (r as any).metadata.name === 'open-webui'
+    ) as any
+    const container = app.spec.template.spec.containers[0]
+    expect(container.image).toBe('ghcr.io/open-webui/open-webui:latest')
+    expect(container.ports[0].containerPort).toBe(8080)
+    expect(container.livenessProbe.httpGet).toEqual({ path: '/health', port: 8080 })
+    expect(container.readinessProbe.httpGet).toEqual({ path: '/health', port: 8080 })
+    // First boot runs Alembic migrations — probes give the app room
+    expect(container.livenessProbe.initialDelaySeconds).toBe(30)
+    expect(container.livenessProbe.failureThreshold).toBe(6)
+    expect(container.readinessProbe.initialDelaySeconds).toBe(30)
+    expect(container.readinessProbe.failureThreshold).toBe(6)
+    expect(container.volumeMounts).toEqual([{ name: 'uploads', mountPath: '/app/backend/data' }])
+    expect(app.spec.template.spec.volumes).toEqual([
+      { name: 'uploads', persistentVolumeClaim: { claimName: 'open-webui-uploads' } },
+    ])
+  })
+
+  it('renders no PVC or volumes when storage is not set', () => {
+    const result = renderOpenWebui({ host: 'chat.example.com' })
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).not.toContain('PersistentVolumeClaim')
+    const app = result.resources.find(
+      (r) => r.kind === 'Deployment' && (r as any).metadata.name === 'open-webui'
+    ) as any
+    const container = app.spec.template.spec.containers[0]
+    expect(container.volumeMounts).toBeUndefined()
+    expect(app.spec.template.spec.volumes).toBeUndefined()
+  })
+
+  it('provisions Redis replication and REDIS_URL against the master service', () => {
+    const result = renderOpenWebui({ host: 'chat.example.com', cache: true })
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('RedisReplication')
+    expect(kinds).not.toContain('RedisCluster')
+
+    const redis = result.resources.find((r) => r.kind === 'RedisReplication') as any
+    expect(redis.metadata.name).toBe('open-webui-redis')
+    expect(redis.spec.clusterSize).toBe(3)
+    expect(redis.spec.kubernetesConfig.image).toBe('redis:7.2-alpine')
+
+    const app = result.resources.find(
+      (r) => r.kind === 'Deployment' && (r as any).metadata.name === 'open-webui'
+    ) as any
+    const redisUrl = app.spec.template.spec.containers[0].env.find(
+      (e: any) => e.name === 'REDIS_URL'
+    )
+    expect(redisUrl.value).toBe('redis://open-webui-redis:6379')
+  })
+
+  it('defaults ENABLE_OLLAMA_API to false', () => {
+    const result = renderOpenWebui({ host: 'chat.example.com' })
+    const app = result.resources.find(
+      (r) => r.kind === 'Deployment' && (r as any).metadata.name === 'open-webui'
+    ) as any
+    const env = app.spec.template.spec.containers[0].env
+    expect(env.find((e: any) => e.name === 'ENABLE_OLLAMA_API').value).toBe('false')
+    assertUniqueEnvNames(env)
+  })
+
+  it('renders gateway resources when platform uses gateway routing', () => {
+    const result = render(
+      jsx(RoutingContext.Provider, {
+        value: { mode: 'gateway', gatewayClassName: 'eg' },
+        children: jsx(SecretContext.Provider, {
+          value: openbao as never,
+          children: jsx(OpenWebui, { host: 'chat.example.com' }),
+        }),
+      })
+    )
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('HTTPRoute')
+  })
+
+  it('renders a valid Ingress when platform uses ingress routing', () => {
+    const result = render(
+      jsx(RoutingContext.Provider, {
+        value: { mode: 'ingress' },
+        children: jsx(SecretContext.Provider, {
+          value: openbao as never,
+          children: jsx(OpenWebui, { host: 'chat.example.com' }),
+        }),
+      })
+    )
+    const ingress = result.resources.find((r) => r.kind === 'Ingress') as any
+    expect(ingress).toBeDefined()
+    expect(ingress.spec.rules[0].host).toBe('chat.example.com')
+  })
+
+  it('points the Ingress at the service on port 8080', () => {
+    const result = renderOpenWebui({ host: 'chat.example.com' })
+    const ingress = result.resources.find((r) => r.kind === 'Ingress') as any
+    expect(ingress.spec.rules[0].http.paths[0].backend.service.name).toBe('open-webui')
+    expect(ingress.spec.rules[0].http.paths[0].backend.service.port.number).toBe(8080)
+  })
+
+  it('passes resource validation', () => {
+    const result = renderOpenWebui({
+      host: 'chat.example.com',
+      storage: '10Gi',
+      cache: true,
+      sso: {
+        issuer: 'https://keycloak.example.com/realms/platform',
+        clientId: 'open-webui',
+        clientSecretRef: { secret: 'open-webui-sso', key: 'clientSecret' },
+      },
+    })
+    for (const resource of result.resources) {
+      expect(validateResource(resource)).toEqual([])
+    }
+  })
+})
+
+describe('rendering with all props', () => {
+  it('accepts the full prop surface', () => {
+    const result = renderOpenWebui({
+      name: 'chat',
+      namespace: 'chat',
+      version: 'v0.6.5',
+      host: 'chat.example.com',
+      replicas: 3,
+      backend: 'https://api.example.com/v1',
+      cache: true,
+      sso: {
+        issuer: 'https://keycloak.example.com/realms/platform',
+        clientId: 'chat',
+        clientSecretRef: { secret: 'chat-sso', key: 'clientSecret' },
+        scopes: 'openid email profile groups',
+      },
+      resources: {
+        requests: { memory: '1Gi', cpu: '500m' },
+        limits: { memory: '4Gi', cpu: '2000m' },
+      },
+      tls: { secretName: 'chat-tls', clusterIssuer: 'letsencrypt-prod' },
+    })
+    expect(result.resources.length).toBeGreaterThan(0)
+
+    const app = result.resources.find(
+      (r) => r.kind === 'Deployment' && (r as any).metadata.name === 'chat'
+    ) as any
+    const container = app.spec.template.spec.containers[0]
+    expect(container.image).toBe('ghcr.io/open-webui/open-webui:v0.6.5')
+    expect(app.spec.replicas).toBe(3)
+    expect(container.resources.limits.memory).toBe('4Gi')
+
+    const backendUrl = container.env.find((e: any) => e.name === 'OPENAI_API_BASE_URL')
+    expect(backendUrl.value).toBe('https://api.example.com/v1')
+
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('RedisReplication')
+    expect(kinds).toContain('Ingress')
+    expect(kinds).toContain('Cluster')
+    assertUniqueEnvNames(container.env)
+  })
+})
+
+describe('offline mode', () => {
+  it('sets OFFLINE_MODE, disables update checks and keeps Ollama off', () => {
+    const result = renderOpenWebui({ host: 'chat.example.com', offline: true })
+    const app = result.resources.find(
+      (r) => r.kind === 'Deployment' && (r as any).metadata.name === 'open-webui'
+    ) as any
+    const env = app.spec.template.spec.containers[0].env
+    expect(env.find((e: any) => e.name === 'OFFLINE_MODE').value).toBe('true')
+    expect(env.find((e: any) => e.name === 'ENABLE_UPDATE_CHECK').value).toBe('false')
+    expect(env.find((e: any) => e.name === 'ENABLE_OLLAMA_API').value).toBe('false')
+    assertUniqueEnvNames(env)
+  })
+
+  it('leaves runtime networking untouched when offline is not set', () => {
+    const result = renderOpenWebui({ host: 'chat.example.com' })
+    const app = result.resources.find(
+      (r) => r.kind === 'Deployment' && (r as any).metadata.name === 'open-webui'
+    ) as any
+    const env = app.spec.template.spec.containers[0].env
+    expect(env.find((e: any) => e.name === 'OFFLINE_MODE')).toBeUndefined()
+    expect(env.find((e: any) => e.name === 'ENABLE_UPDATE_CHECK')).toBeUndefined()
+  })
+})
+
+describe('secrets handling', () => {
+  it('provisions the model API key and secret key through OpenBao', () => {
+    const result = renderOpenWebui({ host: 'chat.example.com' })
+    const kind = result.resources.find((r) => r.kind === 'OpenBaoStaticSecret') as any
+    expect(kind).toBeDefined()
+    expect(kind.metadata.name).toBe('open-webui-secrets')
+    expect(kind.spec.path).toBe('test/open-webui/secrets')
+    expect(kind.spec.destination).toEqual({ create: true, name: 'open-webui-secrets' })
+  })
+
+  it('provisions the keys through Vault', () => {
+    const result = render(
+      jsx(SecretContext.Provider, {
+        value: { backend: 'vault', mount: 'kv', path: 'apps' },
+        children: jsx(OpenWebui, { host: 'chat.example.com' }),
+      })
+    )
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('VaultStaticSecret')
+    expect(kinds).not.toContain('OpenBaoStaticSecret')
+  })
+
+  it('accepts an explicit secretsName without a backend', () => {
+    expect(() =>
+      render(jsx(OpenWebui, { host: 'chat.example.com', secretsName: 'existing-secrets' }))
+    ).not.toThrow()
+    const result = render(
+      jsx(OpenWebui, { host: 'chat.example.com', secretsName: 'existing-secrets' })
+    )
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).not.toContain('OpenBaoStaticSecret')
+    expect(kinds).not.toContain('VaultStaticSecret')
+  })
+
+  it('wires credentials via secretKeyRef (never plaintext env)', () => {
+    const result = renderOpenWebui({ host: 'chat.example.com', secretsName: 'existing-secrets' })
+    const app = result.resources.find(
+      (r) => r.kind === 'Deployment' && (r as any).metadata.name === 'open-webui'
+    ) as any
+    const env = app.spec.template.spec.containers[0].env
+    const modelKey = env.find((e: any) => e.name === 'OPENAI_API_KEY')
+    const webuiSecret = env.find((e: any) => e.name === 'WEBUI_SECRET_KEY')
+    const dbPassword = env.find((e: any) => e.name === 'PGPASSWORD')
+    expect(modelKey.valueFrom.secretKeyRef.name).toBe('existing-secrets')
+    expect(modelKey.valueFrom.secretKeyRef.key).toBe('modelApiKey')
+    expect(webuiSecret.valueFrom.secretKeyRef.name).toBe('existing-secrets')
+    expect(webuiSecret.valueFrom.secretKeyRef.key).toBe('secretKey')
+    expect(dbPassword.valueFrom.secretKeyRef.name).toBe('open-webui-db-credentials')
+    expect(dbPassword.valueFrom.secretKeyRef.key).toBe('password')
+    expect(modelKey.value).toBeUndefined()
+    expect(webuiSecret.value).toBeUndefined()
+    expect(dbPassword.value).toBeUndefined()
+  })
+
+  it('declares secretKeyRef env entries before dependent $(VAR) expansion', () => {
+    const result = renderOpenWebui({ host: 'chat.example.com' })
+    const app = result.resources.find(
+      (r) => r.kind === 'Deployment' && (r as any).metadata.name === 'open-webui'
+    ) as any
+    const env = app.spec.template.spec.containers[0].env
+    const names = env.map((e: any) => e.name)
+    assertUniqueEnvNames(env)
+    expect(names.indexOf('PGPASSWORD')).toBeLessThan(names.indexOf('DATABASE_URL'))
+    const databaseUrl = env.find((e: any) => e.name === 'DATABASE_URL')
+    expect(databaseUrl.value).toBe(
+      'postgresql://open-webui:$(PGPASSWORD)@open-webui-rw:5432/open-webui'
+    )
+    const modelKey = env.find((e: any) => e.name === 'OPENAI_API_KEY')
+    const backendUrl = env.find((e: any) => e.name === 'OPENAI_API_BASE_URL')
+    expect(names.indexOf('OPENAI_API_KEY')).toBeLessThan(names.indexOf('OPENAI_API_BASE_URL'))
+    expect(modelKey.valueFrom.secretKeyRef.name).toBe('open-webui-secrets')
+    expect(backendUrl.value).toBe('https://api.berget.ai/v1')
+  })
+
+  it('renders no plaintext credentials anywhere', () => {
+    const result = renderOpenWebui({
+      host: 'chat.example.com',
+      storage: '10Gi',
+      cache: true,
+      sso: {
+        issuer: 'https://keycloak.example.com/realms/platform',
+        clientId: 'open-webui',
+        clientSecretRef: { secret: 'open-webui-sso', key: 'clientSecret' },
+      },
+    })
+    const { passed, errors } = runGuardrails(result.resources as any[], [noPlaintextSecrets])
+    if (!passed) {
+      console.error('Plaintext credential violations:', errors)
+    }
+    expect(passed).toBe(true)
+  })
+})
+
+describe('sso wiring', () => {
+  it('wires upstream OAUTH env names and the client secret via secretKeyRef', () => {
+    const result = renderOpenWebui({
+      host: 'chat.example.com',
+      sso: {
+        issuer: 'https://keycloak.example.com/realms/platform',
+        clientId: 'open-webui',
+        clientSecretRef: { secret: 'open-webui-sso', key: 'clientSecret' },
+        scopes: 'openid email profile',
+      },
+    })
+    const app = result.resources.find(
+      (r) => r.kind === 'Deployment' && (r as any).metadata.name === 'open-webui'
+    ) as any
+    const env = app.spec.template.spec.containers[0].env
+    const names = env.map((e: any) => e.name)
+    assertUniqueEnvNames(env)
+
+    const clientId = env.find((e: any) => e.name === 'OAUTH_CLIENT_ID')
+    const clientSecret = env.find((e: any) => e.name === 'OAUTH_CLIENT_SECRET')
+    const providerUrl = env.find((e: any) => e.name === 'OPENID_PROVIDER_URL')
+    const scopes = env.find((e: any) => e.name === 'OAUTH_SCOPES')
+    const redirectUri = env.find((e: any) => e.name === 'OPENID_REDIRECT_URI')
+    expect(clientId.value).toBe('open-webui')
+    expect(clientSecret.valueFrom.secretKeyRef.name).toBe('open-webui-sso')
+    expect(clientSecret.valueFrom.secretKeyRef.key).toBe('clientSecret')
+    expect(clientSecret.value).toBeUndefined()
+    // OPENID_PROVIDER_URL is the issuer — Open WebUI appends the
+    // /.well-known/openid-configuration discovery path itself
+    expect(providerUrl.value).toBe('https://keycloak.example.com/realms/platform')
+    expect(scopes.value).toBe('openid email profile')
+    expect(redirectUri.value).toBe('https://chat.example.com/oauth/oidc/callback')
+    expect(env.find((e: any) => e.name === 'ENABLE_OAUTH_SIGNUP').value).toBe('true')
+    // legacy env names must not leak
+    expect(names).not.toContain('OPENID_CLIENT_ID')
+    expect(names).not.toContain('OPENID_CLIENT_SECRET')
+    expect(names).not.toContain('OPENID_SCOPES')
+    expect(names).not.toContain('ENABLE_OPENID_SIGNUP')
+  })
+})
+
+describe('validation errors', () => {
+  it('throws when no secrets backend and no existing Secret ref', () => {
+    expect(() => render(jsx(OpenWebui, { host: 'chat.example.com' }))).toThrow(
+      /application secrets/
+    )
+  })
+
+  it('throws for unknown secrets backends', () => {
+    expect(() =>
+      render(
+        jsx(SecretContext.Provider, {
+          value: { backend: 'unknown' as never },
+          children: jsx(OpenWebui, { host: 'chat.example.com' }),
+        })
+      )
+    ).toThrow(/application secrets/)
+  })
+
+  it('throws when storage is combined with multiple replicas (RWO single attach)', () => {
+    expect(() =>
+      renderOpenWebui({ host: 'chat.example.com', storage: '10Gi', replicas: 2 })
+    ).toThrow(/storage with replicas/)
+  })
+
+  it('allows single-replica storage and multi-replica without storage', () => {
+    expect(() =>
+      renderOpenWebui({ host: 'chat.example.com', storage: '10Gi', replicas: 1 })
+    ).not.toThrow()
+    expect(() => renderOpenWebui({ host: 'chat.example.com', replicas: 3 })).not.toThrow()
+  })
+})

package/examples/basic.tsx

@@ -0,0 +1,8 @@
+import { Platform } from '@r8s/recipes'
+import { OpenWebui } from '@r8s/open-webui'
+
+export default (
+  <Platform secrets={{ backend: 'openbao', mount: 'kv', path: 'apps' }}>
+    <OpenWebui name="chat" host="chat.example.com" version="v0.6.5" storage="10Gi" />
+  </Platform>
+)

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@r8s/open-webui",
+  "version": "0.2.0",
+  "description": "Open WebUI — chat frontend for OpenAI-compatible backends, Postgres persistence, uploads/RAG storage, OIDC SSO, optional Redis cache",
+  "license": "MIT",
+  "author": "Berget AI AB",
+  "homepage": "https://r8s.berget.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/berget-ai/r8s.git",
+    "directory": "packages/open-webui"
+  },
+  "bugs": "https://github.com/berget-ai/r8s/issues",
+  "keywords": [
+    "open-webui",
+    "chat",
+    "llm",
+    "ai"
+  ],
+  "r8s": {
+    "category": "AI & Chat"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc --build",
+    "test": "vitest run",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  },
+  "category": "AI & Assistants",
+  "dependencies": {
+    "@r8s/core": "^0.2.0",
+    "@r8s/crds": "^0.2.0",
+    "@r8s/k8s-types": "^0.2.0",
+    "@r8s/recipes": "^0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  }
+}

package/src/index.tsx

@@ -0,0 +1,426 @@
+import { jsx, Fragment, useContext, declareOperator } from '@r8s/core'
+import { OperatorContext, SecretContext } from '@r8s/core/defaults'
+import { operators } from '@r8s/crds'
+import { Database, Endpoint } from '@r8s/recipes'
+import type { SecretRef } from '@r8s/recipes'
+import { RedisReplicationComponent } from '@r8s/crds/redis'
+import { Deployment, Service, EnvVar, PersistentVolumeClaim } from '@r8s/k8s-types'
+
+export interface OpenWebuiProps {
+  /** Resource name (defaults to 'open-webui') */
+  name?: string
+  /** Kubernetes namespace (defaults to 'default') */
+  namespace?: string
+  /** Container image tag (defaults to 'latest' — pin a version in production) */
+  version?: string
+  /** Public hostname for the chat UI (required) */
+  host: string
+  /**
+   * Number of replicas (defaults to 1). Multiple replicas need a shared
+   * object store for uploads/RAG (this recipe errors when `storage` is
+   * set with replicas > 1 — its PVC is ReadWriteOnce) and Redis-backed
+   * websocket coordination (WEBSOCKET_MANAGER=redis + REDIS_URL).
+   */
+  replicas?: number
+  /**
+   * PVC size for uploads and RAG document storage (e.g. '10Gi'). When set,
+   * a `${name}-uploads` PersistentVolumeClaim is rendered and mounted at
+   * /app/backend/data. WebService cannot express volume mounts, which is
+   * why this component composes a raw Deployment (probes /health:8080).
+   * The PVC is ReadWriteOnce — combining this with replicas > 1 throws
+   * (single-node attach); multi-replica installs must move files/RAG to
+   * an S3-compatible store and set WEBSOCKET_MANAGER=redis.
+   */
+  storage?: string
+  /**
+   * OpenAI-compatible API base URL for the model backend (defaults to
+   * 'https://api.berget.ai/v1'). The key itself is never passed as a
+   * prop — it arrives via secretKeyRef from the secrets bundle below.
+   */
+  backend?: string
+  /**
+   * Name of an existing Secret holding `modelApiKey` (the key used to
+   * call `backend`) and `secretKey` (the WEBUI_SECRET_KEY used to sign
+   * auth tokens). Required unless a secrets backend (openbao/vault) is
+   * configured on the surrounding Platform — the backend then provisions
+   * both keys automatically. Plaintext keys are not supported.
+   */
+  secretsName?: string
+  /**
+   * OAuth/OIDC SSO client — register Open WebUI as a client in Keycloak
+   * (the Auth recipe) and reference the client secret through the backend.
+   * Uses the upstream OAUTH_* env names; OPENID_PROVIDER_URL carries the
+   * issuer (Open WebUI appends /.well-known/openid-configuration itself).
+   */
+  sso?: {
+    /** OIDC discovery issuer, e.g. https://keycloak.example.com/realms/platform */
+    issuer: string
+    /** Client id registered at the issuer (non-sensitive) */
+    clientId: string
+    /** Reference to the Kubernetes Secret holding the client secret */
+    clientSecretRef: SecretRef
+    /** Scope list (defaults to 'openid email profile') */
+    scopes?: string
+  }
+  /** Provision a redis-backed replication group for caching/events (default: false) */
+  cache?: boolean
+  /**
+   * Air-gapped installs: sets OFFLINE_MODE (disable runtime model/param
+   * fetches), removes the update checks and disables the native Ollama
+   * API — only OpenAI-compatible backends are served (default: false).
+   */
+  offline?: boolean
+  /** Requested resources */
+  resources?: {
+    requests?: { cpu?: string; memory?: string }
+    limits?: { cpu?: string; memory?: string }
+  }
+  /** TLS configuration (defaults to letsencrypt-prod cluster issuer) */
+  tls?: {
+    secretName: string
+    clusterIssuer: string
+  }
+}
+
+const OPERATOR_REDIS = 'redis-operator'
+
+/**
+ * Open WebUI — self-hosted chat frontend for OpenAI-compatible backends.
+ *
+ * @title OpenWebui
+ * @category AI & Chat
+ *
+ * Composes:
+ * - CNPG Postgres cluster (users, chats, presets) via the Database recipe
+ * - Open WebUI Deployment + Service + Endpoint (websocket-friendly
+ *   proxy annotations; works through Ingress or Envoy Gateway)
+ * - Optional PVC for uploaded files and RAG documents
+ *   (`${name}-uploads` mounted at /app/backend/data)
+ * - Optional redis replication group for caching (`cache`,
+ *   service ${name}-redis)
+ * - Model API key + WEBUI_SECRET_KEY provisioned through the Platform
+ *   secrets backend (openbao / vault), or referenced from an existing
+ *   Secret
+ * - OAuth/OIDC SSO against the Keycloak `Auth` recipe
+ *
+ * Wrap the component in `<Platform secrets={{ backend: 'openbao' }}>` and
+ * the OPENAI_API_KEY / WEBUI_SECRET_KEY pair is provisioned for you.
+ * Without a backend you must point `secretsName` at a pre-created Secret.
+ * The Perplexity-style "search the web" extras are not wired — only
+ * OPENAI-models via the OpenAI-compatible `backend`.
+ *
+ * @example
+ * import { Platform } from '@r8s/recipes'
+ * import { OpenWebui } from '@r8s/open-webui'
+ *
+ * export default (
+ *   <Platform secrets={{ backend: 'openbao', mount: 'kv', path: 'apps' }}>
+ *     <OpenWebui
+ *       name="chat"
+ *       host="chat.example.com"
+ *       version="v0.6.5"
+ *       storage="10Gi"
+ *     />
+ *   </Platform>
+ * )
+ *
+ * @example
+ * import { Platform } from '@r8s/recipes'
+ * import { OpenWebui } from '@r8s/open-webui'
+ *
+ * export default (
+ *   <Platform secrets={{ backend: 'openbao', mount: 'kv', path: 'apps' }}>
+ *     <OpenWebui
+ *       name="chat"
+ *       host="chat.example.com"
+ *       storage="10Gi"
+ *       cache
+ *       sso={{
+ *         issuer: 'https://keycloak.example.com/realms/platform',
+ *         clientId: 'open-webui',
+ *         clientSecretRef: { secret: 'chat-sso', key: 'clientSecret' },
+ *       }}
+ *     />
+ *   </Platform>
+ * )
+ */
+export function OpenWebui(props: OpenWebuiProps) {
+  const {
+    name = 'open-webui',
+    namespace = 'default',
+    version = 'latest',
+    host,
+    replicas = 1,
+    storage,
+    backend = 'https://api.berget.ai/v1',
+    secretsName,
+    sso,
+    cache = false,
+    offline = false,
+    resources = {
+      requests: { memory: '1Gi', cpu: '500m' },
+      limits: { memory: '4Gi', cpu: '2000m' },
+    },
+    tls = { secretName: `${name}-tls`, clusterIssuer: 'letsencrypt-prod' },
+  } = props
+
+  const sharedOperators = useContext(OperatorContext)
+  const secretProvider = useContext(SecretContext)
+  const resources_: ReturnType<typeof jsx>[] = []
+
+  // --- Validation -----------------------------------------------------------
+  // The uploads PVC is ReadWriteOnce: a single volume can only be attached
+  // to one node at a time, so extra replicas with `storage` set would
+  // crash-loop. Multi-replica installs are viable only with a shared
+  // S3-compatible object store and WEBSOCKET_MANAGER=redis for socket
+  // fan-out.
+  if (storage && replicas > 1) {
+    throw new Error(
+      `OpenWebui "${name}" cannot combine storage with replicas > 1.\n` +
+        `\n` +
+        `The ${name}-uploads PVC is ReadWriteOnce and Open WebUI keeps ` +
+        `uploads/RAG on it — mounting it on multiple nodes is impossible, ` +
+        `so extra replicas would stay Unschedulable or crash-loop. ` +
+        `Multi-replica deployments also need WEBSOCKET_MANAGER=redis plus a ` +
+        `REDIS_URL for socket coordination.\n` +
+        `\n` +
+        `Fix: either run a single replica alongside the PVC:\n` +
+        `  <OpenWebui name="${name}" host="${host}" storage="${storage}" replicas={1} />\n` +
+        `\n` +
+        `Or drop the storage prop and move uploads to S3-compatible storage ` +
+        `with a Redis instance (cache) before scaling out:\n` +
+        `  <OpenWebui name="${name}" host="${host}" replicas={3} cache />`
+    )
+  }
+
+  const dbHost = `${name}-rw`
+  const dbCredentialsName = `${name}-db-credentials`
+  const appSecretsName = secretsName ?? `${name}-secrets`
+
+  // --- Secret provisioning -------------------------------------------------
+  // The model API key and the WEBUI_SECRET_KEY are the crown jewels of an
+  // Open WebUI install — never render them as plaintext. With a secrets
+  // backend they are provisioned through the backend (keys `modelApiKey`
+  // and `secretKey`); otherwise reference a pre-created Secret.
+  if (!secretsName) {
+    if (
+      !secretProvider ||
+      (secretProvider.backend !== 'vault' && secretProvider.backend !== 'openbao')
+    ) {
+      throw new Error(
+        `OpenWebui "${name}" requires application secrets (OPENAI_API_KEY, WEBUI_SECRET_KEY).\n` +
+          `\n` +
+          `The model API key for "${backend}" and the auth-token signing key must ` +
+          `not be rendered as plaintext.\n` +
+          `\n` +
+          `Fix: configure a secrets backend on the Platform:\n` +
+          `  <Platform secrets={{ backend: 'openbao', mount: 'kv', path: 'apps' }}>\n` +
+          `    <OpenWebui name="${name}" host="${host}" />\n` +
+          `  </Platform>\n` +
+          `\n` +
+          `Or reference a pre-created Secret (keys: modelApiKey, secretKey):\n` +
+          `  <OpenWebui name="${name}" host="${host}" secretsName="${name}-secrets" />`
+      )
+    }
+
+    const spec = {
+      ...(secretProvider.backend === 'vault'
+        ? { vaultAuthRef: secretProvider.authRef }
+        : { openbaoAuthRef: secretProvider.authRef }),
+      mount: secretProvider.mount,
+      type: 'kv-v2' as const,
+      path: `${secretProvider.path ?? name}/${name}/secrets`,
+      destination: { create: true, name: appSecretsName },
+    }
+    resources_.push(
+      secretProvider.backend === 'vault'
+        ? jsx('VaultStaticSecret', {
+            apiVersion: 'secrets.hashicorp.com/v1beta1',
+            kind: 'VaultStaticSecret',
+            metadata: { name: `${name}-secrets`, namespace },
+            spec,
+          })
+        : jsx('OpenBaoStaticSecret', {
+            apiVersion: 'secrets.openbao.org/v1beta1',
+            kind: 'OpenBaoStaticSecret',
+            metadata: { name: `${name}-secrets`, namespace },
+            spec,
+          })
+    )
+  }
+
+  // --- Operators ------------------------------------------------------------
+  if (cache && !sharedOperators.some((op) => op.name === OPERATOR_REDIS)) {
+    resources_.push(declareOperator(operators[OPERATOR_REDIS]()))
+  }
+
+  // Redis — caching (OT-Container-Kit operator). A replication group so
+  // the single ${name}-redis master service fronts a 3-node replication
+  // set (1 master + 2 replicas) instead of a lone stateful pod.
+  if (cache) {
+    resources_.push(
+      RedisReplicationComponent({
+        metadata: { name: `${name}-redis`, namespace },
+        spec: {
+          clusterSize: 3,
+          kubernetesConfig: { image: 'redis:7.2-alpine' },
+        },
+      })
+    )
+  }
+
+  // --- Uploads/RAG PVC --------------------------------------------------------
+  // WebService cannot mount volumes, so the app controller below is a raw
+  // Deployment. The PVC is rendered alongside and bound when `storage` is
+  // set. Without it, uploaded files and RAG documents are lost on restart.
+  if (storage) {
+    const pvc: PersistentVolumeClaim = {
+      apiVersion: 'v1',
+      kind: 'PersistentVolumeClaim',
+      metadata: { name: `${name}-uploads`, namespace },
+      spec: {
+        accessModes: ['ReadWriteOnce'],
+        resources: { requests: { storage } },
+      },
+    }
+    resources_.push(jsx('PersistentVolumeClaim', pvc))
+  }
+
+  // --- Env wiring --------------------------------------------------------------
+  // Every credential arrives via secretKeyRef — declared BEFORE plain env
+  // vars in the container env array, so Kubernetes dependent-variable
+  // expansion resolves the $(VAR) templates below at runtime.
+  const secretRefs: Record<string, SecretRef | string> = {
+    PGPASSWORD: { secret: dbCredentialsName, key: 'password' },
+    OPENAI_API_KEY: { secret: appSecretsName, key: 'modelApiKey' },
+    WEBUI_SECRET_KEY: { secret: appSecretsName, key: 'secretKey' },
+    ...(sso ? { OAUTH_CLIENT_SECRET: sso.clientSecretRef } : {}),
+  }
+
+  const envVars: EnvVar[] = []
+  for (const [envName, ref] of Object.entries(secretRefs)) {
+    const typed = typeof ref === 'string' ? { secret: ref } : ref
+    envVars.push({
+      name: envName,
+      valueFrom: { secretKeyRef: { name: typed.secret, key: typed.key ?? envName } },
+    })
+  }
+
+  const env: Record<string, string> = {
+    WEBUI_URL: `https://${host}`,
+    ENABLE_OPENAI_API: 'true',
+    // This recipe targets OpenAI-compatible backends only — the native
+    // Ollama API discovery stays off (offline mode forces the same).
+    ENABLE_OLLAMA_API: 'false',
+    OPENAI_API_BASE_URL: backend,
+    // Deterministic parts inlined; the password arrives via $(PGPASSWORD)
+    // (secret-backed var declared first in the env array).
+    DATABASE_URL: `postgresql://${name}:$(PGPASSWORD)@${dbHost}:5432/${name}`,
+    ...(cache ? { REDIS_URL: `redis://${name}-redis:6379` } : {}),
+    // Upstream OAUTH_* names; ENABLE_OAUTH_SIGNUP (default true) governs
+    // whether local-password login is offered alongside the SSO flow.
+    ...(sso
+      ? {
+          ENABLE_OAUTH_SIGNUP: 'true',
+          OPENID_PROVIDER_URL: sso.issuer,
+          OAUTH_CLIENT_ID: sso.clientId,
+          OPENID_REDIRECT_URI: `https://${host}/oauth/oidc/callback`,
+          OAUTH_SCOPES: sso.scopes ?? 'openid email profile',
+        }
+      : {}),
+    ...(offline
+      ? {
+          OFFLINE_MODE: 'true',
+          ENABLE_UPDATE_CHECK: 'false',
+        }
+      : {}),
+  }
+  for (const [key, value] of Object.entries(env)) {
+    envVars.push({ name: key, value })
+  }
+
+  // --- App controller (raw Deployment — WebService cannot mount volumes) -----
+  // Generous probe delays/failures: first-boot runs Alembic migrations
+  // against Postgres before /health starts answering.
+  const deployment: Deployment = {
+    apiVersion: 'apps/v1',
+    kind: 'Deployment',
+    metadata: { name, namespace, labels: { app: name } },
+    spec: {
+      replicas,
+      selector: { matchLabels: { app: name } },
+      template: {
+        metadata: { labels: { app: name } },
+        spec: {
+          containers: [
+            {
+              name: 'open-webui',
+              image: `ghcr.io/open-webui/open-webui:${version}`,
+              imagePullPolicy: 'Always',
+              ports: [{ containerPort: 8080 }],
+              env: envVars,
+              resources,
+              livenessProbe: {
+                httpGet: { path: '/health', port: 8080 },
+                initialDelaySeconds: 30,
+                periodSeconds: 10,
+                failureThreshold: 6,
+              },
+              readinessProbe: {
+                httpGet: { path: '/health', port: 8080 },
+                initialDelaySeconds: 30,
+                periodSeconds: 5,
+                failureThreshold: 6,
+              },
+              ...(storage && {
+                volumeMounts: [{ name: 'uploads', mountPath: '/app/backend/data' }],
+              }),
+            },
+          ],
+          ...(storage && {
+            volumes: [{ name: 'uploads', persistentVolumeClaim: { claimName: `${name}-uploads` } }],
+          }),
+        },
+      },
+    },
+  }
+
+  // Database parent wraps the app so the CNPG cluster, its credentials
+  // secret (${name}-db-credentials) and connection conventions stay
+  // consistent with the r8s Database recipe. The raw Deployment sets
+  // DATABASE_URL statically (the WebService auto-PG block does not apply).
+  resources_.push(
+    jsx(Database, { name, namespace, storage: '10Gi', children: jsx('Deployment', deployment) })
+  )
+
+  // --- Service -----------------------------------------------------------------
+  const service: Service = {
+    apiVersion: 'v1',
+    kind: 'Service',
+    metadata: { name, namespace },
+    spec: {
+      type: 'ClusterIP',
+      selector: { app: name },
+      ports: [{ port: 8080, targetPort: 8080 }],
+    },
+  }
+  resources_.push(jsx('Service', service))
+
+  // --- Endpoint — websocket-friendly proxy timeouts ------------------------------
+  resources_.push(
+    <Endpoint
+      name={`${name}-endpoint`}
+      namespace={namespace}
+      host={host}
+      serviceName={name}
+      servicePort={8080}
+      tls={tls}
+      annotations={{
+        'nginx.ingress.kubernetes.io/proxy-read-timeout': '300',
+        'nginx.ingress.kubernetes.io/proxy-send-timeout': '300',
+      }}
+    />
+  )
+
+  return jsx(Fragment, { children: resources_ })
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "composite": true
+  },
+  "include": ["src/**/*"],
+  "references": [
+    { "path": "../core" },
+    { "path": "../k8s-types" },
+    { "path": "../crds" },
+    { "path": "../recipes" }
+  ]
+}