Install

This guide installs NocoDB for production with external PostgreSQL and Redis. After install, you connect object storage for attachments in the admin panel.

1. Prepare your datastores

1. Set up a PostgreSQL database and a Redis instance. NocoDB runs its own schema migrations at startup, so the database user needs DDL privileges on its schema.
2. Enable TLS on PostgreSQL and Redis where possible.
3. Set up an S3-compatible bucket for attachments. You connect it in the NocoDB admin panel after install (refer to step 5), not through the chart. Thus, no S3 credentials go into your Kubernetes Secret.

2. Create the secret

Create one Kubernetes Secret that holds your connection strings and credentials. The chart reads these keys:

kubectl create namespace nocodb
kubectl -n nocodb create secret generic nocodb-secrets \
  --from-literal=DATABASE_URL='postgresql://user:pass@db.internal:5432/nocodb?sslmode=require' \
  --from-literal=NC_REDIS_URL='rediss://:pass@redis.internal:6379'

3. Install the chart

helm install nocodb oci://ghcr.io/nocodb/charts/nocodb --version 1.0.0 \
  -n nocodb --create-namespace -f values.yaml

This is a minimal production values.yaml:

replicaCount: 2
worker:
  enabled: true
  replicaCount: 2
externalDatabase:
  existingSecret: nocodb-secrets
externalRedis:
  existingSecret: nocodb-secrets
ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: nocodb.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: nocodb-tls
      hosts: [nocodb.example.com]

Make sure that the rollout is successful:

kubectl -n nocodb rollout status deploy/nocodb
kubectl -n nocodb exec deploy/nocodb -- wget -qO- http://localhost:8080/api/v1/health

4. Ingress and TLS

1. Set ingress.enabled: true.
2. Set an ingress.className.
3. Add a cert-manager cluster-issuer annotation, or supply your own TLS secret under ingress.tls.

The chart gets NC_SITE_URL from the first ingress host automatically. It uses https when TLS is configured. To use a different value, set nocodb.publicUrl.

5. Configure attachment storage

NocoDB stores uploaded files in object storage. You configure the storage in the app, not in the chart. When the app is available:

1. Sign in as a super admin.
2. Open the App Store.
3. Set up an S3-compatible Storage plugin with your bucket and credentials. Supported providers include AWS S3, MinIO, Google Cloud Storage and others.

NocoDB saves the setting in the metadata database, so all app and worker replicas use it automatically. For the full list of supported providers, refer to App Store integrations.

6. High availability

The app and the worker scale independently:

• App: scale freely. Run replicaCount: 2+ (requires Redis), or enable the HPA with autoscaling.enabled: true. App pods are stateless. Redis sends WebSocket events to all replicas, so you do not need sticky sessions.
• Worker: for stability, use a fixed worker.replicaCount of 2 or more (refer to Background workers below).
• Enable a PodDisruptionBudget with pdb.create: true. It covers the app and the worker.
• The chart has a soft pod anti-affinity by default (podAntiAffinityPreset: soft).

7. Background workers

Workers process the shared Bull job queue (imports, thumbnails, migrations). Workers require Redis.

Run a fixed worker.replicaCount of 2 or more. Do not autoscale workers. Workers run asynchronous jobs. A scale-down or a rolling update stops a pod, and that pod can be in the middle of a job.

At shutdown, NocoDB tries to finish running jobs within worker.terminationGracePeriodSeconds (default 120s). Set it to a value above the duration of your longest job. If a worker stops before it finishes, Bull runs the job again on another worker through stalled-job recovery. Thus, jobs should be idempotent.

Worker autoscaling is available (worker.autoscaling.enabled: true, with a minimum of 2 replicas). It is off by default. Enable it only if your jobs are short and idempotent, and you have tuned the grace period. To tune throughput, use worker.replicaCount and worker.concurrency.

8. SSO

1. Set sso.oidc.enabled: true (or sso.saml.enabled: true).
2. Supply the provider client secrets through extraEnvVars that refer to your secret.

For the variables, refer to environment variables.

9. Observability

NocoDB does not expose a Prometheus metrics endpoint. Collect container logs with your cluster logging stack. For error reports, you can also set monitoring.sentry.enabled: true. Pod and cluster metrics come from the standard kube-state-metrics / cAdvisor stack.

10. Additional configuration

For settings that the chart does not model directly, use extraEnvVars, extraVolumes/extraVolumeMounts and extraDeploy. For PostgreSQL with a private CA, mount the CA through extraVolumes and set NC_DB_JSON_FILE through extraEnvVars.

Production checklist

• External PostgreSQL and Redis configured, and attachment storage set up in the App Store
• All credentials through existingSecret (no inline secrets)
• resources reviewed (the defaults request 1 vCPU and 2 GiB memory for each pod, with 1 GiB memory minimum)
• pdb.create: true and anti-affinity in place
• autoscaling.enabled: true (or a fixed replicaCount ≥ 2)
• TLS configured through ingress
• Image tag pinned (defaults to the chart's appVersion)
• Database backups configured
• Readiness verified through /api/v1/health

Parameters reference

For the full parameter table, refer to the chart README.md.