refactor: externalize postgres

.github/workflows/helm.yaml

@@ -11,6 +11,11 @@ jobs:
       - uses: actions/checkout@v6
       - uses: ./.github/actions/setup-nix
 
+      - name: Render templates with dummy values
+        run: |
+          nix develop --no-pure-eval --accept-flake-config "./tools/nix#ci" --command \
+            just helm::template --values tools/helm/lint-values.yaml
+
       - name: Log in to GHCR
         env:
           GHCR_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -1,7 +1,12 @@
 **/charts/*.tgz
 config.toml
-*.dec.*
-.env
+*.env
 .devenv/
 .direnv/
 .output/
+
+# agentic setup
+.agents/
+.claude/
+AGENTS.md
+CLAUDE.md

.helmignore

@@ -2,14 +2,13 @@
 # This supports shell glob matching, relative path matching, and
 # negation (prefixed with !). Only one pattern per line.
 .DS_Store
-scripts
-otlp-openmeter-bridge
 .github
+# Sources for the images the chart references (built separately, not part of the chart)
+src
 # Dev tooling and docs (not part of the chart)
 tools
 docs
 justfile
-CONTRIBUTING.md
 .devenv/
 .direnv/
 .output/
@@ -38,3 +37,9 @@ values.*.yaml
 .idea/
 *.tmproj
 
+# agentic files
+
+.agents/
+AGENTS.md
+.claude/
+CLAUDE.md

.tpl.env

@@ -0,0 +1,4 @@
+# Copy to .env and fill in. Values are paths to secret files kept outside the repository.
+# Used by `just db-bootstrap`.
+OPENWEBUI_PG_PASSWORD_FILE=
+AUTHENTIK_PG_PASSWORD_FILE=

Chart.lock

@@ -1,9 +1,6 @@
 dependencies:
-- name: postgresql
-  repository: https://charts.bitnami.com/bitnami
-  version: 18.7.0
 - name: authentik
   repository: https://goauthentik.github.io/helm
   version: 2026.5.2
-digest: sha256:2f5bc89396b1bb7a388a1c12c221d8f4a194812e83e54bd1839fb9bdb53e1b1c
-generated: "2026-06-04T09:20:49.97286315+02:00"
+digest: sha256:7cf416b44f9132417c0006541e59049f9a44a28e36f003842cd334781523d8a5
+generated: "2026-08-04T00:00:00.000000000+02:00"

Chart.yaml

@@ -5,10 +5,6 @@ appVersion: latest
 description: Helm chart for vLLM inference on vanilla Kubernetes
 type: application
 dependencies:
-  - name: postgresql
-    version: 18.x
-    repository: https://charts.bitnami.com/bitnami
-    condition: postgresql.enabled
   - name: authentik
     version: 2026.x
     repository: https://goauthentik.github.io/helm

README.md

@@ -12,12 +12,13 @@ The chart only creates custom resources that rely on these systems being install
 - [Envoy Gateway](https://gateway.envoyproxy.io/) with the [Envoy AI Gateway](https://aigateway.envoyproxy.io/) extension (controller in `envoy-gateway-system`)
 - [Knative Serving](https://knative.dev/docs/serving/) (scale-to-zero model services)
 - [cert-manager](https://cert-manager.io/) with a `ClusterIssuer` matching `envoy.clusterissuer`
+- A PostgreSQL server, with roles and databases created up front. See [postgresql.md](docs/postgresql.md)
 
 ## Usage
 
 The repository contains a [`justfile`](justfile) to automate routine commands.
 You may use it as reference, or run it with `just` (by default, just will list available recipes).
-See [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
+See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for more information.
 
 ### Helm (Kubernetes)
 
@@ -38,10 +39,8 @@ helm upgrade --install -n <your namespace> vllm . --values values.<env>.yaml
 
 where `<your namespace>` is your Kubernetes namespace.
 
-Components have no enforced apply ordering: PostgreSQL, Authentik, OpenWebUI, the
-gateway, and the models reconcile independently, and pods restart until their
-dependencies are ready. The init job runs as a `post-install,post-upgrade` Helm
-hook, after the rest of the release is applied.
+The init job runs as a `post-install,post-upgrade` Helm hook, after the rest of the
+release is applied.
 
 To preview the rendered manifests before applying:
 
@@ -65,8 +64,10 @@ models:
     fullName: "Qwen/Qwen2.5-Omni-7B-AWQ" # name of the hosted model on huggingface
     internal: true # true means this is a model hosted by us, false would be for forwarding to external apis (experimental)
     nodeType: "A100" # the type of GPU to use
-    apiKey: # the API key to use for external APIs, if not hosted by us
-    image: # the vllm image to use for hosting the model, can be left empty
+    apiKey: # required: the API key to use for external APIs, if not hosted by us.
+    image: # optional: the vllm image to use for hosting the model
+      # repository:
+      # tag:
     cacheDir: # the directory for the vllm cache (leaving this empty should work in most cases)
       # path: /myhome
       # claimName: # the PVC claim to mount the cache to. On runai, use something like `pvc-<project>-home` (e.g. `pvc-codev-ralf-home`)

docs/postgresql.md

@@ -0,0 +1,56 @@
+# PostgreSQL
+
+The chart connects to an external PostgreSQL server, which
+must be reachable from the cluster and accept TLS: both OpenWebUI and Authentik connect with
+`sslmode=require`.
+
+## Roles and databases
+
+The databases and roles need to be created ahead of time. We provide a helper just recipe to do it.
+
+To use it, run this before installing:
+
+```bash
+just db-bootstrap <host> [<admin-user>] [<openwebui-db>] [<authentik-db>]
+```
+
+The recipe reads the two application passwords from the files named in `.env` (copy
+`.tpl.env` and fill in the paths), and prompts for the admin password. It needs an account
+allowed to `CREATE ROLE` and `CREATE DATABASE`; on a managed or central server you may have
+to ask a DBA to run [bootstrap-db.sql](../tools/scripts/bootstrap-db.sql) instead. Either way
+it is safe to re-run: existing roles and databases are left untouched.
+
+> [!NOTE]
+>
+> The sql script sends the application passwords in `CREATE ROLE` statements, so connect over TLS.
+> The recipe does this for you. When running manually, use :
+>
+> ```bash
+> psql "postgresql://<admin>@<host>/postgres?sslmode=require" -f tools/scripts/bootstrap-db.sql
+> ```
+
+## Values
+
+The postgres values must be specified for `authentik` and `openwebui`. They may use the same
+server, but should have different roles and databases.
+
+## Sharing a server between releases
+
+The names default to `vllm-openwebui` and `vllm-authentik`, if multiple
+releases share one server. Scope them per release, and pass the same names to
+`just db-bootstrap`:
+
+```yaml
+openwebui:
+  postgres:
+    database: staging-openwebui
+authentik:
+  authentik:
+    postgresql:
+      name: staging-authentik
+      user: staging-authentik
+```
+
+A collision does not fail loudly: the bootstrap skips roles that already exist, so a second
+release either fails to authenticate or, if the password was copied across, quietly shares
+the first release's database. Give each release its own names, or its own server.

justfile

@@ -77,6 +77,20 @@ test *args:
 deploy namespace release values_file:
     helm upgrade --install -n "{{namespace}}" "{{release}}" . --values "{{values_file}}"
 
+# init roles and databases. psql prompts for the admin password.
+[group('chart')]
+db-bootstrap host admin_user="postgres" openwebui_db="vllm-openwebui" authentik_db="vllm-authentik":
+    #!/usr/bin/env bash
+    set -eu
+    : "${OPENWEBUI_PG_PASSWORD_FILE:?not set, see .tpl.env}"
+    : "${AUTHENTIK_PG_PASSWORD_FILE:?not set, see .tpl.env}"
+    OPENWEBUI_PG_DATABASE="{{openwebui_db}}" \
+    AUTHENTIK_PG_DATABASE="{{authentik_db}}" \
+    OPENWEBUI_PG_PASSWORD="$(< "$OPENWEBUI_PG_PASSWORD_FILE")" \
+    AUTHENTIK_PG_PASSWORD="$(< "$AUTHENTIK_PG_PASSWORD_FILE")" \
+        psql "postgresql://{{admin_user}}@{{host}}/postgres?sslmode=require" \
+            --file "{{root_dir}}/tools/scripts/bootstrap-db.sql"
+
 # Errors if the repository contains unformatted files.
 [private]
 check-format *args:

templates/models/knative-serving.yaml

@@ -1,4 +1,8 @@
 {{- range $name, $model := .Values.models }}
+  {{- /* default optional sub-maps so a missing key does not fail. */}}
+  {{- $persistence := $model.persistence | default dict }}
+  {{- $image := $model.image | default dict }}
+  {{- $cacheDir := $model.cacheDir | default dict }}
   {{- if $model.dummy }}
 ---
 apiVersion: serving.knative.dev/v1
@@ -64,12 +68,12 @@ spec:
               nvidia.com/gpu: {{ $model.resources.limits.gpu }}
     {{- end }}
           volumeMounts:
-    {{- if $model.persistence.enabled }}
-          - mountPath: {{ $model.cacheDir.path | default "/myhome" }}
+    {{- if $persistence.enabled }}
+          - mountPath: {{ $cacheDir.path | default "/myhome" }}
             name: pvc-cache
             subPath: {{ $.Values.environment | default "." }}/model_cache/
-    {{- else if (and $model.cacheDir $model.cacheDir.claimName) }}
-          - mountPath: {{ $model.cacheDir.path }}
+    {{- else if (and $cacheDir $cacheDir.claimName) }}
+          - mountPath: {{ $cacheDir.path }}
             name: pvc-cache
             subPath: {{ $.Values.environment | default "." }}/model_cache
     {{- end }}
@@ -93,11 +97,11 @@ spec:
       timeoutSeconds: 600
       responseStartTimeoutSeconds: 600
       idleTimeoutSeconds: 600
-    {{- if or $model.persistence.enabled (and $model.cacheDir $model.cacheDir.claimName) }}
+    {{- if or $persistence.enabled (and $cacheDir $cacheDir.claimName) }}
       volumes:
         - name: pvc-cache
           persistentVolumeClaim:
-            claimName: {{ if $model.persistence.enabled }}{{ $.Release.Name }}-model-{{ $name }}-cache{{ else }}{{ $model.cacheDir.claimName }}{{ end }}
+            claimName: {{ if $persistence.enabled }}{{ $.Release.Name }}-model-{{ $name }}-cache{{ else }}{{ $cacheDir.claimName }}{{ end }}
     {{- end }}
   traffic:
     - latestRevision: true
@@ -126,7 +130,7 @@ spec:
     spec:
       containers:
         - name: user-container
-          image: "{{ $model.image.repository | default "vllm/vllm-openai" }}:{{ $model.image.tag | default "latest" }}"
+          image: "{{ $image.repository | default "vllm/vllm-openai" }}:{{ $image.tag | default "latest" }}"
           imagePullPolicy: IfNotPresent
     {{- if not $model.defaultCommand}}
           command:
@@ -173,9 +177,9 @@ spec:
                 secretKeyRef:
                   name: vllm-secret-{{ $name }}
                   key: apiKey
-    {{- if or $model.persistence.enabled $model.cacheDir }}
+    {{- if or $persistence.enabled $cacheDir }}
             - name: VLLM_CACHE_ROOT
-              value: {{ $model.cacheDir.path | default "/myhome" }}
+              value: {{ $cacheDir.path | default "/myhome" }}
     {{- end }}
           startupProbe:
             httpGet:
@@ -213,14 +217,14 @@ spec:
           ports:
             - containerPort: 8000
               protocol: TCP
-          workingDir: {{ $model.cacheDir.path | default "/myhome" }}
+          workingDir: {{ $cacheDir.path | default "/myhome" }}
           volumeMounts:
-    {{- if $model.persistence.enabled }}
-          - mountPath: {{ $model.cacheDir.path | default "/myhome" }}
+    {{- if $persistence.enabled }}
+          - mountPath: {{ $cacheDir.path | default "/myhome" }}
             name: pvc-cache
             subPath: {{ $.Values.environment | default "." }}/model_cache/
-    {{- else if (and $model.cacheDir $model.cacheDir.claimName) }}
-          - mountPath: {{ $model.cacheDir.path }}
+    {{- else if (and $cacheDir $cacheDir.claimName) }}
+          - mountPath: {{ $cacheDir.path }}
             name: pvc-cache
             subPath: {{ $.Values.environment | default "." }}/model_cache
     {{- end }}
@@ -238,11 +242,11 @@ spec:
       affinity:
         {{- toYaml $.Values.global.affinity | nindent 8 }}
     {{- end }}
-    {{- if or $model.persistence.enabled (and $model.cacheDir $model.cacheDir.claimName) }}
+    {{- if or $persistence.enabled (and $cacheDir $cacheDir.claimName) }}
       volumes:
         - name: pvc-cache
           persistentVolumeClaim:
-            claimName: {{ if $model.persistence.enabled }}{{ $.Release.Name }}-model-{{ $name }}-cache{{ else }}{{ $model.cacheDir.claimName }}{{ end }}
+            claimName: {{ if $persistence.enabled }}{{ $.Release.Name }}-model-{{ $name }}-cache{{ else }}{{ $cacheDir.claimName }}{{ end }}
     {{- end }}
       timeoutSeconds: 600
       responseStartTimeoutSeconds: 600

templates/models/pvc.yaml

@@ -1,5 +1,8 @@
 {{- range $name, $model := .Values.models }}
-  {{- if and $model.internal $model.persistence.enabled }}
+  {{- /* These sub-maps are optional in values.yaml; default them so a missing
+  key renders empty instead of failing with a nil pointer. */}}
+  {{- $persistence := $model.persistence | default dict }}
+  {{- if and $model.internal $persistence.enabled }}
 ---
 apiVersion: v1
 kind: PersistentVolumeClaim
@@ -10,10 +13,10 @@ metadata:
     release: {{ $.Release.Name }}
 spec:
   accessModes:
-    - {{ $model.persistence.accessMode | default "ReadWriteOnce" }}
-  storageClassName: {{ $model.persistence.storageClass | default "default" }}
+    - {{ $persistence.accessMode | default "ReadWriteOnce" }}
+  storageClassName: {{ $persistence.storageClass | default "default" }}
   resources:
     requests:
-      storage: {{ $model.persistence.size | default "50Gi" }}
+      storage: {{ $persistence.size | default "50Gi" }}
   {{- end }}
 {{- end }}

templates/openwebui/deployment.yaml

@@ -32,21 +32,22 @@ spec:
               value: "true"
             - name: OPENAI_API_BASE_URL
               value: https://gateway.{{ .Values.envoy.baseDomain }}/v1
-  {{- if .Values.openwebui.postgres }}
             - name: DATABASE_URL
               valueFrom:
                 secretKeyRef:
                   name: postgres-secret
                   key: OPENWEBUI_DATABASE_URL
-  {{- end }}
             - name: ENABLE_OAUTH_SIGNUP
               value: "true"
             - name: ENABLE_LOGIN_FORM
               value: "true"
             - name: OAUTH_CLIENT_ID
               value: {{ .Values.authentik.oauthApp.clientId | required ".Values.authentik.oauthApp.clientId is required" }}
             - name: OAUTH_CLIENT_SECRET
-              value: {{ .Values.authentik.oauthApp.clientSecret | required ".Values.authentik.oauthApp.clientSecret is required" }}
+              valueFrom:
+                secretKeyRef:
+                  name: openwebui-oauth
+                  key: OAUTH_CLIENT_SECRET
             - name: OAUTH_ADMIN_ROLES
               value: gateway admins
             - name: OPENID_PROVIDER_URL
@@ -81,7 +82,8 @@ spec:
               path: /health
               port: 8080
             periodSeconds: 10
-            failureThreshold: 1
+            # Liveness should catch a deadlocked process, not one slow health check.
+            failureThreshold: 3
           resources:
             requests:
               cpu: {{ .Values.openwebui.resources.requests.cpu | quote }}

templates/openwebui/oauth_secret.yaml

@@ -0,0 +1,10 @@
+{{- if .Values.openwebui.enabled }}
+  {{- /* Kept out of the Deployment so the credential is not readable from the pod spec. */}}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: "openwebui-oauth"
+type: Opaque
+stringData:
+  OAUTH_CLIENT_SECRET: {{ .Values.authentik.oauthApp.clientSecret | required ".Values.authentik.oauthApp.clientSecret is required" }}
+{{- end }}