feat(helm): add Helm chart for Kubernetes deployment and update DeploymentGuide

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
2026-02-25 13:31:54 +00:00
parent ff96340154
commit a08bfb9f1a
19 changed files with 1424 additions and 158 deletions
@@ -0,0 +1,10 @@
+# Patterns to ignore when building packages.
+.DS_Store
+.git
+.gitignore
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+.vscode
@@ -0,0 +1,37 @@
+apiVersion: v2
+name: docuelevate
+description: >
+  DocuElevate — intelligent document processing with OCR, AI metadata
+  extraction, full-text search (Meilisearch), and multi-cloud storage.
+
+type: application
+
+# Chart version — bump on every chart change (independent of appVersion).
+version: 0.1.0
+
+# Application version — kept in sync with the VERSION file.
+appVersion: "0.54.0"
+
+keywords:
+  - document-management
+  - ocr
+  - ai
+  - meilisearch
+  - fastapi
+  - celery
+
+home: https://github.com/christianlouis/DocuElevate
+sources:
+  - https://github.com/christianlouis/DocuElevate
+
+maintainers:
+  - name: DocuElevate Contributors
+    url: https://github.com/christianlouis/DocuElevate
+
+dependencies:
+  # Bundled Redis (optional — disable and point to an external instance via
+  # externalRedis.url if you already have Redis in the cluster).
+  - name: redis
+    version: "20.x.x"
+    repository: "https://charts.bitnami.com/bitnami"
+    condition: redis.enabled
@@ -0,0 +1,45 @@
+Thank you for installing {{ .Chart.Name }} {{ .Chart.Version }}!
+
+{{- if .Values.ingress.enabled }}
+The application will be available at:
+{{- range .Values.ingress.hosts }}
+  http{{ if $.Values.ingress.tls }}s{{ end }}://{{ .host }}
+{{- end }}
+{{- else }}
+To access DocuElevate, run:
+
+  kubectl port-forward svc/{{ include "docuelevate.fullname" . }}-api {{ .Values.api.service.port }}:{{ .Values.api.service.port }} -n {{ .Release.Namespace }}
+
+Then open http://localhost:{{ .Values.api.service.port }}
+{{- end }}
+
+API docs are available at: <your-url>/docs
+
+{{- if not .Values.secrets.SESSION_SECRET }}
+
+⚠️  WARNING: secrets.SESSION_SECRET is not set.
+   Generate one with:  openssl rand -hex 32
+   Then pass it via:   --set secrets.SESSION_SECRET=<value>
+   or via a values file / external secret.
+
+{{- end }}
+
+{{- if not .Values.secrets.DATABASE_URL }}
+
+⚠️  WARNING: secrets.DATABASE_URL is not set.
+   For production, use PostgreSQL:
+     postgresql://user:pass@host:5432/docuelevate
+   SQLite with a PVC is supported but not recommended for multi-replica
+   deployments (use ReadWriteOnce PVC and replicaCount=1 in that case).
+
+{{- end }}
+
+Useful commands:
+  # View API logs
+  kubectl logs -l app.kubernetes.io/component=api -n {{ .Release.Namespace }} -f
+
+  # View worker logs
+  kubectl logs -l app.kubernetes.io/component=worker -n {{ .Release.Namespace }} -f
+
+  # Run a database migration manually
+  kubectl create job --from=cronjob/{{ include "docuelevate.fullname" . }}-migrate migrate-manual -n {{ .Release.Namespace }}
@@ -0,0 +1,108 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "docuelevate.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+We truncate at 63 chars because some Kubernetes name fields are limited to this.
+If release name contains chart name it will be used as a full name.
+*/}}
+{{- define "docuelevate.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create chart label value: "chart-name-version"
+*/}}
+{{- define "docuelevate.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels applied to every resource.
+*/}}
+{{- define "docuelevate.labels" -}}
+helm.sh/chart: {{ include "docuelevate.chart" . }}
+{{ include "docuelevate.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels.
+*/}}
+{{- define "docuelevate.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "docuelevate.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{/*
+ServiceAccount name.
+*/}}
+{{- define "docuelevate.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "docuelevate.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}
+
+{{/*
+Image reference, using appVersion as default tag.
+*/}}
+{{- define "docuelevate.image" -}}
+{{- $tag := .Values.image.tag | default .Chart.AppVersion }}
+{{- printf "%s:%s" .Values.image.repository $tag }}
+{{- end }}
+
+{{/*
+Resolve REDIS_URL: prefer externalRedis.url, then secrets.REDIS_URL,
+then fall back to the bundled Redis service URL.
+*/}}
+{{- define "docuelevate.redisUrl" -}}
+{{- if .Values.externalRedis.url }}
+{{- .Values.externalRedis.url }}
+{{- else if .Values.secrets.REDIS_URL }}
+{{- .Values.secrets.REDIS_URL }}
+{{- else if .Values.redis.enabled }}
+{{- printf "redis://%s-redis-master:6379/0" .Release.Name }}
+{{- else }}
+{{- "" }}
+{{- end }}
+{{- end }}
+
+{{/*
+Resolve GOTENBERG_URL — use env override if set, otherwise build from service name.
+*/}}
+{{- define "docuelevate.gotenbergUrl" -}}
+{{- if .Values.env.GOTENBERG_URL }}
+{{- tpl .Values.env.GOTENBERG_URL . }}
+{{- else }}
+{{- printf "http://%s-gotenberg:3000" (include "docuelevate.fullname" .) }}
+{{- end }}
+{{- end }}
+
+{{/*
+Resolve MEILISEARCH_URL — use env override if set, otherwise build from service name.
+*/}}
+{{- define "docuelevate.meilisearchUrl" -}}
+{{- if .Values.env.MEILISEARCH_URL }}
+{{- tpl .Values.env.MEILISEARCH_URL . }}
+{{- else }}
+{{- printf "http://%s-meilisearch:7700" (include "docuelevate.fullname" .) }}
+{{- end }}
+{{- end }}
@@ -0,0 +1,93 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "docuelevate.fullname" . }}-api
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "docuelevate.labels" . | nindent 4 }}
+    app.kubernetes.io/component: api
+spec:
+  {{- if not .Values.api.autoscaling.enabled }}
+  replicas: {{ .Values.api.replicaCount }}
+  {{- end }}
+  selector:
+    matchLabels:
+      {{- include "docuelevate.selectorLabels" . | nindent 6 }}
+      app.kubernetes.io/component: api
+  template:
+    metadata:
+      labels:
+        {{- include "docuelevate.selectorLabels" . | nindent 8 }}
+        app.kubernetes.io/component: api
+      {{- with .Values.api.podAnnotations }}
+      annotations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+    spec:
+      serviceAccountName: {{ include "docuelevate.serviceAccountName" . }}
+      {{- with .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.api.podSecurityContext }}
+      securityContext:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      containers:
+        - name: api
+          image: {{ include "docuelevate.image" . }}
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          command:
+            - uvicorn
+            - app.main:app
+            - --host
+            - "0.0.0.0"
+            - --port
+            - "8000"
+            - --proxy-headers
+          ports:
+            - name: http
+              containerPort: 8000
+              protocol: TCP
+          envFrom:
+            - configMapRef:
+                name: {{ include "docuelevate.fullname" . }}-config
+            - secretRef:
+                name: {{ include "docuelevate.fullname" . }}-secret
+          {{- with .Values.api.livenessProbe }}
+          livenessProbe:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
+          {{- with .Values.api.readinessProbe }}
+          readinessProbe:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
+          {{- with .Values.api.securityContext }}
+          securityContext:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
+          resources:
+            {{- toYaml .Values.api.resources | nindent 12 }}
+          volumeMounts:
+            - name: workdir
+              mountPath: /workdir
+      volumes:
+        - name: workdir
+          {{- if .Values.workdir.persistence.enabled }}
+          persistentVolumeClaim:
+            claimName: {{ .Values.workdir.persistence.existingClaim | default (printf "%s-workdir" (include "docuelevate.fullname" .)) }}
+          {{- else }}
+          emptyDir: {}
+          {{- end }}
+      {{- with .Values.api.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.api.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.api.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
@@ -0,0 +1,18 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "docuelevate.fullname" . }}-api
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "docuelevate.labels" . | nindent 4 }}
+    app.kubernetes.io/component: api
+spec:
+  type: {{ .Values.api.service.type }}
+  ports:
+    - port: {{ .Values.api.service.port }}
+      targetPort: http
+      protocol: TCP
+      name: http
+  selector:
+    {{- include "docuelevate.selectorLabels" . | nindent 4 }}
+    app.kubernetes.io/component: api
@@ -0,0 +1,40 @@
+# Non-sensitive application configuration.
+# All values are injected as environment variables into the API and Worker pods.
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ include "docuelevate.fullname" . }}-config
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "docuelevate.labels" . | nindent 4 }}
+data:
+  WORKDIR: {{ .Values.env.WORKDIR | quote }}
+  PYTHONPATH: "/app"
+  PYTHONUNBUFFERED: "1"
+
+  # AI provider
+  AI_PROVIDER: {{ .Values.env.AI_PROVIDER | quote }}
+  OPENAI_MODEL: {{ .Values.env.OPENAI_MODEL | quote }}
+
+  # Azure
+  AZURE_REGION: {{ .Values.env.AZURE_REGION | quote }}
+  AZURE_ENDPOINT: {{ .Values.env.AZURE_ENDPOINT | quote }}
+
+  # Service URLs — resolved from helper templates so they always match the
+  # in-cluster service names even if values.yaml uses template expressions.
+  GOTENBERG_URL: {{ include "docuelevate.gotenbergUrl" . | quote }}
+  MEILISEARCH_URL: {{ include "docuelevate.meilisearchUrl" . | quote }}
+  MEILISEARCH_INDEX_NAME: {{ .Values.env.MEILISEARCH_INDEX_NAME | quote }}
+  ENABLE_SEARCH: {{ .Values.env.ENABLE_SEARCH | quote }}
+
+  # Auth
+  AUTH_ENABLED: {{ .Values.env.AUTH_ENABLED | quote }}
+  ADMIN_USERNAME: {{ .Values.env.ADMIN_USERNAME | quote }}
+  EXTERNAL_HOSTNAME: {{ .Values.env.EXTERNAL_HOSTNAME | quote }}
+
+  # Feature flags
+  ENABLE_DEDUPLICATION: {{ .Values.env.ENABLE_DEDUPLICATION | quote }}
+  ENABLE_TEXT_QUALITY_CHECK: {{ .Values.env.ENABLE_TEXT_QUALITY_CHECK | quote }}
+  ALLOW_FILE_DELETE: {{ .Values.env.ALLOW_FILE_DELETE | quote }}
+
+  DEBUG: {{ .Values.env.DEBUG | quote }}
@@ -0,0 +1,63 @@
+{{- if .Values.gotenberg.enabled }}
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "docuelevate.fullname" . }}-gotenberg
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "docuelevate.labels" . | nindent 4 }}
+    app.kubernetes.io/component: gotenberg
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      {{- include "docuelevate.selectorLabels" . | nindent 6 }}
+      app.kubernetes.io/component: gotenberg
+  template:
+    metadata:
+      labels:
+        {{- include "docuelevate.selectorLabels" . | nindent 8 }}
+        app.kubernetes.io/component: gotenberg
+    spec:
+      containers:
+        - name: gotenberg
+          image: {{ .Values.gotenberg.image.repository }}:{{ .Values.gotenberg.image.tag }}
+          imagePullPolicy: {{ .Values.gotenberg.image.pullPolicy }}
+          ports:
+            - name: http
+              containerPort: 3000
+              protocol: TCP
+          resources:
+            {{- toYaml .Values.gotenberg.resources | nindent 12 }}
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: 3000
+            initialDelaySeconds: 10
+            periodSeconds: 30
+          readinessProbe:
+            httpGet:
+              path: /health
+              port: 3000
+            initialDelaySeconds: 5
+            periodSeconds: 10
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "docuelevate.fullname" . }}-gotenberg
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "docuelevate.labels" . | nindent 4 }}
+    app.kubernetes.io/component: gotenberg
+spec:
+  type: ClusterIP
+  ports:
+    - port: {{ .Values.gotenberg.service.port }}
+      targetPort: http
+      protocol: TCP
+      name: http
+  selector:
+    {{- include "docuelevate.selectorLabels" . | nindent 4 }}
+    app.kubernetes.io/component: gotenberg
+{{- end }}
@@ -0,0 +1,51 @@
+{{- if .Values.api.autoscaling.enabled }}
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: {{ include "docuelevate.fullname" . }}-api
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "docuelevate.labels" . | nindent 4 }}
+    app.kubernetes.io/component: api
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: {{ include "docuelevate.fullname" . }}-api
+  minReplicas: {{ .Values.api.autoscaling.minReplicas }}
+  maxReplicas: {{ .Values.api.autoscaling.maxReplicas }}
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: {{ .Values.api.autoscaling.targetCPUUtilizationPercentage }}
+{{- end }}
+
+---
+
+{{- if .Values.worker.autoscaling.enabled }}
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: {{ include "docuelevate.fullname" . }}-worker
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "docuelevate.labels" . | nindent 4 }}
+    app.kubernetes.io/component: worker
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: {{ include "docuelevate.fullname" . }}-worker
+  minReplicas: {{ .Values.worker.autoscaling.minReplicas }}
+  maxReplicas: {{ .Values.worker.autoscaling.maxReplicas }}
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: {{ .Values.worker.autoscaling.targetCPUUtilizationPercentage }}
+{{- end }}
@@ -0,0 +1,36 @@
+{{- if .Values.ingress.enabled -}}
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: {{ include "docuelevate.fullname" . }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "docuelevate.labels" . | nindent 4 }}
+  {{- with .Values.ingress.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  {{- if .Values.ingress.className }}
+  ingressClassName: {{ .Values.ingress.className }}
+  {{- end }}
+  {{- if .Values.ingress.tls }}
+  tls:
+    {{- toYaml .Values.ingress.tls | nindent 4 }}
+  {{- end }}
+  rules:
+    {{- range .Values.ingress.hosts }}
+    - host: {{ .host | quote }}
+      http:
+        paths:
+          {{- range .paths }}
+          - path: {{ .path }}
+            pathType: {{ .pathType }}
+            backend:
+              service:
+                name: {{ include "docuelevate.fullname" $ }}-api
+                port:
+                  number: {{ $.Values.api.service.port }}
+          {{- end }}
+    {{- end }}
+{{- end }}
@@ -0,0 +1,89 @@
+{{- if .Values.meilisearch.enabled }}
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "docuelevate.fullname" . }}-meilisearch
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "docuelevate.labels" . | nindent 4 }}
+    app.kubernetes.io/component: meilisearch
+spec:
+  # Single replica — Meilisearch Community Edition is single-node only.
+  # Use Meilisearch Cloud or the paid Meilisearch Cluster for HA.
+  replicas: 1
+  selector:
+    matchLabels:
+      {{- include "docuelevate.selectorLabels" . | nindent 6 }}
+      app.kubernetes.io/component: meilisearch
+  strategy:
+    # Recreate ensures the PVC is released before the new pod starts
+    type: Recreate
+  template:
+    metadata:
+      labels:
+        {{- include "docuelevate.selectorLabels" . | nindent 8 }}
+        app.kubernetes.io/component: meilisearch
+    spec:
+      containers:
+        - name: meilisearch
+          image: {{ .Values.meilisearch.image.repository }}:{{ .Values.meilisearch.image.tag }}
+          imagePullPolicy: {{ .Values.meilisearch.image.pullPolicy }}
+          ports:
+            - name: http
+              containerPort: 7700
+              protocol: TCP
+          env:
+            - name: MEILI_NO_ANALYTICS
+              value: {{ .Values.meilisearch.env.MEILI_NO_ANALYTICS | quote }}
+            {{- if .Values.secrets.MEILISEARCH_API_KEY }}
+            - name: MEILI_MASTER_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "docuelevate.fullname" . }}-secret
+                  key: MEILISEARCH_API_KEY
+            {{- end }}
+          resources:
+            {{- toYaml .Values.meilisearch.resources | nindent 12 }}
+          volumeMounts:
+            - name: data
+              mountPath: /meili_data
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: 7700
+            initialDelaySeconds: 15
+            periodSeconds: 30
+          readinessProbe:
+            httpGet:
+              path: /health
+              port: 7700
+            initialDelaySeconds: 10
+            periodSeconds: 10
+      volumes:
+        - name: data
+          {{- if .Values.meilisearch.persistence.enabled }}
+          persistentVolumeClaim:
+            claimName: {{ .Values.meilisearch.persistence.existingClaim | default (printf "%s-meilisearch-data" (include "docuelevate.fullname" .)) }}
+          {{- else }}
+          emptyDir: {}
+          {{- end }}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "docuelevate.fullname" . }}-meilisearch
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "docuelevate.labels" . | nindent 4 }}
+    app.kubernetes.io/component: meilisearch
+spec:
+  type: ClusterIP
+  ports:
+    - port: {{ .Values.meilisearch.service.port }}
+      targetPort: http
+      protocol: TCP
+      name: http
+  selector:
+    {{- include "docuelevate.selectorLabels" . | nindent 4 }}
+    app.kubernetes.io/component: meilisearch
+{{- end }}
@@ -0,0 +1,69 @@
+# Database migration Job — runs `alembic upgrade head` once before
+# the API and Worker Deployments start.  Helm hooks ensure ordering:
+# the Job runs during pre-upgrade/pre-install and the Deployments wait
+# for it via the `helm.sh/hook-weight` annotation.
+{{- if .Values.migrations.enabled }}
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: {{ include "docuelevate.fullname" . }}-migrate-{{ .Release.Revision }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "docuelevate.labels" . | nindent 4 }}
+    app.kubernetes.io/component: migrate
+  annotations:
+    "helm.sh/hook": pre-install,pre-upgrade
+    "helm.sh/hook-weight": "-5"
+    "helm.sh/hook-delete-policy": before-hook-creation
+    {{- if .Values.migrations.ttlSecondsAfterFinished }}
+spec:
+  ttlSecondsAfterFinished: {{ .Values.migrations.ttlSecondsAfterFinished }}
+    {{- end }}
+spec:
+  {{- if .Values.migrations.ttlSecondsAfterFinished }}
+  ttlSecondsAfterFinished: {{ .Values.migrations.ttlSecondsAfterFinished }}
+  {{- end }}
+  backoffLimit: 3
+  template:
+    metadata:
+      labels:
+        {{- include "docuelevate.selectorLabels" . | nindent 8 }}
+        app.kubernetes.io/component: migrate
+    spec:
+      restartPolicy: OnFailure
+      serviceAccountName: {{ include "docuelevate.serviceAccountName" . }}
+      {{- with .Values.image.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      containers:
+        - name: migrate
+          image: {{ include "docuelevate.image" . }}
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          command: ["alembic", "upgrade", "head"]
+          envFrom:
+            - configMapRef:
+                name: {{ include "docuelevate.fullname" . }}-config
+            - secretRef:
+                name: {{ include "docuelevate.fullname" . }}-secret
+          {{- with .Values.workdir.persistence }}
+          volumeMounts:
+            - name: workdir
+              mountPath: /workdir
+          {{- end }}
+          resources:
+            requests:
+              cpu: 100m
+              memory: 256Mi
+            limits:
+              cpu: 500m
+              memory: 512Mi
+      volumes:
+        - name: workdir
+          {{- if .Values.workdir.persistence.enabled }}
+          persistentVolumeClaim:
+            claimName: {{ .Values.workdir.persistence.existingClaim | default (printf "%s-workdir" (include "docuelevate.fullname" .)) }}
+          {{- else }}
+          emptyDir: {}
+          {{- end }}
+{{- end }}
@@ -0,0 +1,49 @@
+# Shared workdir PVC — mounted by both the API and the Worker so they can
+# exchange files during processing.  Requires ReadWriteMany (e.g. NFS,
+# CephFS, Azure Files, EFS) when running multiple replicas.
+# Set workdir.persistence.accessMode=ReadWriteOnce and replicaCount=1
+# for single-node / dev clusters.
+{{- if .Values.workdir.persistence.enabled }}
+{{- if not .Values.workdir.persistence.existingClaim }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ include "docuelevate.fullname" . }}-workdir
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "docuelevate.labels" . | nindent 4 }}
+spec:
+  accessModes:
+    - {{ .Values.workdir.persistence.accessMode }}
+  resources:
+    requests:
+      storage: {{ .Values.workdir.persistence.size }}
+  {{- if .Values.workdir.persistence.storageClass }}
+  storageClassName: {{ .Values.workdir.persistence.storageClass }}
+  {{- end }}
+{{- end }}
+{{- end }}
+
+---
+
+# Meilisearch data PVC
+{{- if and .Values.meilisearch.enabled .Values.meilisearch.persistence.enabled }}
+{{- if not .Values.meilisearch.persistence.existingClaim }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ include "docuelevate.fullname" . }}-meilisearch-data
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "docuelevate.labels" . | nindent 4 }}
+spec:
+  accessModes:
+    - {{ .Values.meilisearch.persistence.accessMode }}
+  resources:
+    requests:
+      storage: {{ .Values.meilisearch.persistence.size }}
+  {{- if .Values.meilisearch.persistence.storageClass }}
+  storageClassName: {{ .Values.meilisearch.persistence.storageClass }}
+  {{- end }}
+{{- end }}
+{{- end }}
@@ -0,0 +1,14 @@
+{{- if .Values.serviceAccount.create -}}
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: {{ include "docuelevate.serviceAccountName" . }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "docuelevate.labels" . | nindent 4 }}
+  {{- with .Values.serviceAccount.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+automountServiceAccountToken: false
+{{- end }}
@@ -0,0 +1,82 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "docuelevate.fullname" . }}-worker
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "docuelevate.labels" . | nindent 4 }}
+    app.kubernetes.io/component: worker
+spec:
+  {{- if not .Values.worker.autoscaling.enabled }}
+  replicas: {{ .Values.worker.replicaCount }}
+  {{- end }}
+  selector:
+    matchLabels:
+      {{- include "docuelevate.selectorLabels" . | nindent 6 }}
+      app.kubernetes.io/component: worker
+  template:
+    metadata:
+      labels:
+        {{- include "docuelevate.selectorLabels" . | nindent 8 }}
+        app.kubernetes.io/component: worker
+      {{- with .Values.worker.podAnnotations }}
+      annotations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+    spec:
+      serviceAccountName: {{ include "docuelevate.serviceAccountName" . }}
+      {{- with .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.worker.podSecurityContext }}
+      securityContext:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      containers:
+        - name: worker
+          image: {{ include "docuelevate.image" . }}
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          command:
+            - celery
+            - -A
+            - app.celery_worker
+            - worker
+            - -B
+            - --loglevel=info
+            - -Q
+            - document_processor,default,celery
+          envFrom:
+            - configMapRef:
+                name: {{ include "docuelevate.fullname" . }}-config
+            - secretRef:
+                name: {{ include "docuelevate.fullname" . }}-secret
+          {{- with .Values.worker.securityContext }}
+          securityContext:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
+          resources:
+            {{- toYaml .Values.worker.resources | nindent 12 }}
+          volumeMounts:
+            - name: workdir
+              mountPath: /workdir
+      volumes:
+        - name: workdir
+          {{- if .Values.workdir.persistence.enabled }}
+          persistentVolumeClaim:
+            claimName: {{ .Values.workdir.persistence.existingClaim | default (printf "%s-workdir" (include "docuelevate.fullname" .)) }}
+          {{- else }}
+          emptyDir: {}
+          {{- end }}
+      {{- with .Values.worker.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.worker.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.worker.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
@@ -0,0 +1,306 @@
+# =============================================================================
+# DocuElevate Helm Chart — values.yaml
+#
+# Override any value with:
+#   helm install docuelevate ./helm/docuelevate -f my-values.yaml
+#   helm install docuelevate ./helm/docuelevate --set key=value
+# =============================================================================
+
+# ---------------------------------------------------------------------------
+# Global image settings
+# ---------------------------------------------------------------------------
+image:
+  repository: ghcr.io/christianlouis/docuelevate
+  # Defaults to the chart appVersion; pin to a specific digest in production.
+  tag: ""
+  pullPolicy: IfNotPresent
+
+imagePullSecrets: []
+
+nameOverride: ""
+fullnameOverride: ""
+
+# ---------------------------------------------------------------------------
+# Shared environment — non-secret application config
+# All values map 1-to-1 onto DocuElevate environment variables.
+# Sensitive values (API keys, passwords) go into `secrets` below.
+# ---------------------------------------------------------------------------
+env:
+  # Required ----------------------------------------------------------------
+  WORKDIR: /workdir
+
+  # AI provider (openai | azure | anthropic | gemini | ollama | openrouter)
+  AI_PROVIDER: openai
+  OPENAI_MODEL: gpt-4o-mini
+
+  # Azure Document Intelligence (required when OCR_PROVIDERS includes "azure")
+  AZURE_REGION: eastus
+  AZURE_ENDPOINT: ""   # e.g. https://my-resource.cognitiveservices.azure.com/
+
+  # Gotenberg PDF conversion service
+  GOTENBERG_URL: http://{{ include "docuelevate.fullname" . }}-gotenberg:3000
+
+  # Full-text search — uses the in-cluster Meilisearch service by default
+  MEILISEARCH_URL: http://{{ include "docuelevate.fullname" . }}-meilisearch:7700
+  MEILISEARCH_INDEX_NAME: documents
+  ENABLE_SEARCH: "true"
+
+  # Authentication
+  AUTH_ENABLED: "true"
+  ADMIN_USERNAME: admin
+
+  # Feature flags
+  ENABLE_DEDUPLICATION: "true"
+  ENABLE_TEXT_QUALITY_CHECK: "true"
+  ALLOW_FILE_DELETE: "true"
+
+  # Logging / misc
+  DEBUG: "false"
+  EXTERNAL_HOSTNAME: localhost   # set to your public hostname / Ingress host
+
+# ---------------------------------------------------------------------------
+# Secrets — values are stored in a Kubernetes Secret and injected as env vars.
+# In production, use an external secret manager (Vault, ESO, Sealed Secrets)
+# and leave these blank, then mount the Secret yourself.
+# ---------------------------------------------------------------------------
+secrets:
+  DATABASE_URL: ""         # e.g. postgresql://user:pass@postgres:5432/docuelevate
+  REDIS_URL: ""            # leave blank to use bundled Redis
+  SESSION_SECRET: ""       # min 32-char random string — generate with: openssl rand -hex 32
+  OPENAI_API_KEY: ""
+  AZURE_AI_KEY: ""
+  MEILISEARCH_API_KEY: "" # leave blank for unauthenticated (dev) Meilisearch
+
+  # Storage provider secrets (only the ones you use)
+  DROPBOX_APP_KEY: ""
+  DROPBOX_APP_SECRET: ""
+  DROPBOX_REFRESH_TOKEN: ""
+  GOOGLE_DRIVE_CREDENTIALS_JSON: ""
+  ONEDRIVE_CLIENT_ID: ""
+  ONEDRIVE_CLIENT_SECRET: ""
+  ONEDRIVE_REFRESH_TOKEN: ""
+  AWS_ACCESS_KEY_ID: ""
+  AWS_SECRET_ACCESS_KEY: ""
+
+  # OAuth / Authentik
+  AUTHENTIK_CLIENT_ID: ""
+  AUTHENTIK_CLIENT_SECRET: ""
+  AUTHENTIK_CONFIG_URL: ""
+
+# ---------------------------------------------------------------------------
+# External services
+# Set externalRedis.url (and disable bundled redis) when you have your own.
+# ---------------------------------------------------------------------------
+externalRedis:
+  # When non-empty this value is injected as REDIS_URL, overriding secrets.REDIS_URL
+  # and the auto-generated bundled-Redis URL.
+  url: ""
+
+# ---------------------------------------------------------------------------
+# API deployment
+# ---------------------------------------------------------------------------
+api:
+  replicaCount: 2
+
+  resources:
+    requests:
+      cpu: 250m
+      memory: 512Mi
+    limits:
+      cpu: "1"
+      memory: 1Gi
+
+  # Horizontal Pod Autoscaler
+  autoscaling:
+    enabled: false
+    minReplicas: 2
+    maxReplicas: 8
+    targetCPUUtilizationPercentage: 70
+
+  service:
+    type: ClusterIP
+    port: 8000
+
+  # Liveness / readiness probes
+  livenessProbe:
+    httpGet:
+      path: /api/health
+      port: 8000
+    initialDelaySeconds: 30
+    periodSeconds: 20
+    failureThreshold: 3
+
+  readinessProbe:
+    httpGet:
+      path: /api/health
+      port: 8000
+    initialDelaySeconds: 15
+    periodSeconds: 10
+    failureThreshold: 3
+
+  podAnnotations: {}
+  nodeSelector: {}
+  tolerations: []
+  affinity: {}
+
+  podSecurityContext:
+    runAsNonRoot: true
+    runAsUser: 1000
+    fsGroup: 1000
+
+  securityContext:
+    allowPrivilegeEscalation: false
+    readOnlyRootFilesystem: false  # app writes to /workdir
+    capabilities:
+      drop: ["ALL"]
+
+# ---------------------------------------------------------------------------
+# Celery worker deployment
+# ---------------------------------------------------------------------------
+worker:
+  replicaCount: 2
+
+  resources:
+    requests:
+      cpu: 500m
+      memory: 1Gi
+    limits:
+      cpu: "2"
+      memory: 4Gi
+
+  autoscaling:
+    enabled: false
+    minReplicas: 2
+    maxReplicas: 10
+    targetCPUUtilizationPercentage: 75
+
+  podAnnotations: {}
+  nodeSelector: {}
+  tolerations: []
+  affinity: {}
+
+  podSecurityContext:
+    runAsNonRoot: true
+    runAsUser: 1000
+    fsGroup: 1000
+
+  securityContext:
+    allowPrivilegeEscalation: false
+    readOnlyRootFilesystem: false
+    capabilities:
+      drop: ["ALL"]
+
+# ---------------------------------------------------------------------------
+# Shared workdir volume (api + worker mount the same PVC)
+# ---------------------------------------------------------------------------
+workdir:
+  persistence:
+    enabled: true
+    # storageClass: "" # leave blank for cluster default
+    accessMode: ReadWriteMany  # RWX required for multiple pods
+    size: 20Gi
+    # existingClaim: ""
+
+# ---------------------------------------------------------------------------
+# Gotenberg (PDF conversion)
+# ---------------------------------------------------------------------------
+gotenberg:
+  enabled: true
+  image:
+    repository: gotenberg/gotenberg
+    tag: latest
+    pullPolicy: IfNotPresent
+  service:
+    port: 3000
+  resources:
+    requests:
+      cpu: 100m
+      memory: 256Mi
+    limits:
+      cpu: "1"
+      memory: 1Gi
+
+# ---------------------------------------------------------------------------
+# Meilisearch (full-text search)
+# ---------------------------------------------------------------------------
+meilisearch:
+  enabled: true
+  image:
+    repository: getmeili/meilisearch
+    tag: latest
+    pullPolicy: IfNotPresent
+  service:
+    port: 7700
+  env:
+    MEILI_NO_ANALYTICS: "true"
+    # MEILI_MASTER_KEY: ""  # set via secrets.MEILISEARCH_API_KEY instead
+  persistence:
+    enabled: true
+    # storageClass: ""
+    accessMode: ReadWriteOnce
+    size: 10Gi
+    # existingClaim: ""
+  resources:
+    requests:
+      cpu: 100m
+      memory: 256Mi
+    limits:
+      cpu: "1"
+      memory: 1Gi
+
+# ---------------------------------------------------------------------------
+# Bundled Redis (from Bitnami chart)
+# Disable and set externalRedis.url to use your own.
+# ---------------------------------------------------------------------------
+redis:
+  enabled: true
+  architecture: standalone
+  auth:
+    enabled: false
+  master:
+    persistence:
+      enabled: true
+      size: 4Gi
+    resources:
+      requests:
+        cpu: 100m
+        memory: 128Mi
+      limits:
+        cpu: 500m
+        memory: 512Mi
+
+# ---------------------------------------------------------------------------
+# Ingress
+# ---------------------------------------------------------------------------
+ingress:
+  enabled: false
+  className: ""   # e.g. nginx, traefik
+  annotations: {}
+  # nginx.ingress.kubernetes.io/proxy-body-size: "1g"
+  # cert-manager.io/cluster-issuer: letsencrypt-prod
+  hosts:
+    - host: docuelevate.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+  tls: []
+  # - secretName: docuelevate-tls
+  #   hosts:
+  #     - docuelevate.example.com
+
+# ---------------------------------------------------------------------------
+# ServiceAccount
+# ---------------------------------------------------------------------------
+serviceAccount:
+  create: true
+  annotations: {}
+  name: ""
+
+# ---------------------------------------------------------------------------
+# Database migration job
+# Runs `alembic upgrade head` before the api/worker start.
+# ---------------------------------------------------------------------------
+migrations:
+  enabled: true
+  # Automatically deleted after successful completion
+  ttlSecondsAfterFinished: 120