Kubernetes with Helm
The chart is in deploy/helm/necodoc. Its values.yaml documents every setting.
What it installs
Section titled “What it installs”- Deployments for
api(ROLE=api),worker(ROLE=worker) andapp(the web app), with Services forapiandapp. - An Ingress:
/apito the API, everything else to the app, on one host. - A ConfigMap with the non-secret env, and a Secret (or your existing one).
- A migration Job that runs as a
pre-installandpre-upgradehook, before any new pod starts. - PodDisruptionBudgets for
apiandworker. - Optional: a CPU HorizontalPodAutoscaler or a KEDA ScaledObject for workers, and a PersistentVolumeClaim for disk storage.
- Prometheus metrics on port 9464 of every api and worker pod, with
prometheus.io/*annotations; optionally a Prometheus OperatorPodMonitor. See Observability.
Pods run as non-root (UID 1000; nginx’s 101 for the app) with a read-only root filesystem, no Linux capabilities and the RuntimeDefault seccomp profile. Chromium doesn’t need extra privileges.
The chart doesn’t install Postgres. Use a managed service or an operator such as CloudNativePG.
Install
Section titled “Install”Create a Secret with at least DATABASE_URL and BETTER_AUTH_SECRET, plus any storage credentials (see Configuration):
kubectl create namespace necodockubectl -n necodoc create secret generic necodoc-env \ --from-literal=BETTER_AUTH_SECRET="$(openssl rand -base64 32)"Then a values file:
image: { repository: registry.example.com/necodoc-api, tag: "0.1.0" }appImage: { repository: registry.example.com/necodoc-app, tag: "0.1.0" }publicUrl: https://necodoc.example.comsecrets: { existingSecret: necodoc-env }ingress: className: nginx host: necodoc.example.com tls: [{ secretName: necodoc-tls, hosts: [necodoc.example.com] }]storage: driver: s3 s3: { bucket: necodoc-outputs, region: us-east-1 }helm install necodoc deploy/helm/necodoc -n necodoc -f my-values.yamlYou can put DATABASE_URL and BETTER_AUTH_SECRET under secrets: instead of existingSecret. The chart’s Secret is a Helm hook, so the migration Job can read it on the first install. Because of that, helm uninstall leaves it behind; delete it by hand.
Ingress
Section titled “Ingress”Your controller must allow request bodies of 25 MB (uploads are capped at 20 MB) and upstream reads of RENDER_WAIT_MS plus a margin, 120 seconds with the default (synchronous renders wait up to RENDER_WAIT_MS). Set those through ingress.annotations in your controller’s syntax.
Storage
Section titled “Storage”disk: the chart creates a PVC (or usesstorage.disk.existingClaim) and mounts it at/data/fileson every API and worker pod. With more than one pod it must beReadWriteMany(NFS, EFS, Azure Files, CephFS). It hashelm.sh/resource-policy: keep, so uninstalling keeps your PDFs.s3andazure: no volume. Put keys in the Secret, or leave them out and use workload identity: annotate the chart’s ServiceAccount throughserviceAccount.annotations(IRSA’seks.amazonaws.com/role-arn, orazure.workload.identity/client-id). Azure workload identity also needs theazure.workload.identity/use: "true"pod label, which the chart has no value for: add it with a Helm post-renderer, or use a connection string or account key instead.
Details and examples: Storage.
Scaling workers
Section titled “Scaling workers”Set worker.replicas, or turn on one autoscaler:
worker: autoscaling: { enabled: true, minReplicas: 2, maxReplicas: 10, targetCPUUtilizationPercentage: 70 }Or scale on the render queue with KEDA (install KEDA first):
worker: keda: { enabled: true, minReplicas: 1, maxReplicas: 20, jobsPerReplica: 4 }The ScaledObject counts queued and running jobs on the render queue in pg-boss’s pgboss.job table, using the worker’s DATABASE_URL. The two are exclusive; KEDA creates its own HPA. See Roles and scaling.
Probes
Section titled “Probes”API and worker pods have a startup and liveness probe on /api/health and a readiness probe on /api/health/ready. A pod with no database, queue or storage goes unready. See Health checks.
Upgrade
Section titled “Upgrade”helm upgrade necodoc deploy/helm/necodoc -n necodoc -f my-values.yaml --set image.tag=0.2.0 --set appImage.tag=0.2.0The migration Job runs first; if it fails, the upgrade stops before any pod changes. Pods restart when the chart’s ConfigMap or Secret changes (checksum annotations); after changing an existing Secret, run kubectl rollout restart. See Upgrades.