Overview
NocoDB is a no-code database and smart spreadsheet — a self-hosted alternative to Airtable, Baserow, and Teable — that turns a database into grid, kanban, gallery, and calendar views with forms, webhooks, and a REST API. This template deploys NocoDB Community Edition (web UI, REST and GraphQL APIs, and live updates on port8080) backed by a bundled PostgreSQL for all metadata and a bundled Redis for job events, caching, and rate limiting, with attachments kept on a persistent volume or in an S3 bucket you own. The default is a single replica over a single-instance PostgreSQL; nocodb.replicas scales the app tier once attachments live in S3, and postgresHA.enabled swaps the database for a highly available cluster.
What Gets Created
Prerequisites
Three dictionary secrets must exist before installing: NocoDB’s two signing and encryption keys, the bundled database’s credentials, and the bundled Redis password. The values never pass through Helm values.Create the database credentials secret
postgres.config.credentialsSecretName (single-instance, the default) or postgresHA.config.credentialsSecretName (HA). Use only letters, digits, - and _ in all three values: NocoDB receives them inside its NC_DB connection URL, unencoded, so other characters break the connection. Secret names are org-wide, so give each NocoDB release its own secret. PostgreSQL reads the secret only when its data is first initialized — see Rotating the Database Password.Create the Redis credentials secret
redis.credentialsSecretName to this name. Use only letters, digits, - and _: NocoDB receives the password inside its NC_REDIS_URL, unencoded. Give each NocoDB release its own secret. To change it later, see Rotating the Redis Password.Create the key secret
secrets.name to this name. Secrets are org-level, so no GVC flag is involved.Back both values up outside Control Plane
NC_AUTH_JWT_SECRET logs out every user, and changing NC_CONNECTION_ENCRYPT_KEY makes the stored credentials of external data sources undecryptable — upstream has no re-encryption path. Keep a copy somewhere safe.- S3 attachment storage (required for more than one replica) — an existing bucket plus either an AWS cloud account and bucket-scoped IAM policy, or a static-key secret for an S3-compatible server. See Attachment Storage on S3.
- Super-admin bootstrap — a dictionary secret holding
NC_ADMIN_EMAILandNC_ADMIN_PASSWORD. See Super-Admin Bootstrap. - Authenticated SMTP — a dictionary secret holding
NC_SMTP_USERNAMEandNC_SMTP_PASSWORD. See Email. - Scheduled database backups — a bucket and provider access for the bundled PostgreSQL. See Backing Up.
Installation
Once your three secrets exist, install from the marketplace registry, pointing the chart at them:postgresHA.config.credentialsSecretName instead of postgres.config.credentialsSecretName.
Other ways to install and manage the template:
UI
CLI
Terraform
Pulumi
Configuration
NocoDB Server
nocodb.siteUrl must match the URL browsers actually use. Leave it empty to derive it from the workload’s canonical endpoint; set it, with the https:// scheme, only when you serve NocoDB on a custom domain.
Prerequisite Secret
Super-Admin Bootstrap
By default NocoDB seeds no account and the first person to sign up becomes the super admin. To create the account up front instead, put the credentials in a dictionary secret and reference it by name. The password must be at least 8 characters with an uppercase letter, a digit, and a special character.Attachment Storage
storage.type decides where uploaded files, images, and thumbnails are kept. The default local volume works for a single replica; the bucket, cloud account, and secret setup for s3 is under Attachment Storage on S3.
storage.fileUploadSizeLimit is a byte count, not a size string. An upload over the limit is rejected with HTTP 413 and File too large, not truncated.
host, port, and from are all set; the chart fails the render if smtp.enabled is true and any of them is missing. For an authenticated relay, create the credentials secret before installing and set smtp.auth.secretName to its name. The NocoDB identity is granted reveal on exactly that secret.
Access
publicAccess.enabled: false there is no public endpoint, and an empty nocodb.siteUrl falls back to the internal http://RELEASE_NAME-nocodb.GVC_NAME.cpln.local:8080 address. A change to either access knob takes a couple of minutes to take effect after the upgrade reports success.
Bundled Redis
Redis is required: it carries the job and event pub/sub, the metadata cache, and the rate limiter, and all three are what make more than one replica coherent. It runs withappendonly yes and maxmemory-policy noeviction — an evicted key would silently drop a job event.
Database
Enable exactly one ofpostgres (single instance, the default) and postgresHA (highly available) — the chart refuses to render both on or both off. NocoDB is wired to the active database automatically, including for its boot migrations.
credentialsSecretName (see Prerequisites).
Connecting
publicAccess.enabled: false there is no public endpoint; reach the UI from your machine through a tunnel instead and open http://localhost:8080:
First Run
NocoDB ships no default account. Unless you bootstrap one withadmin.secretName, the first person to sign up becomes the super admin — and the signup form is open to anyone who can reach the endpoint.
Wait for the NocoDB workload to report ready
Sign up and claim the super-admin account
super role. Do this as soon as the workload is ready.Close signup
Configure email before inviting anyone
Operations
Attachment Storage on S3
Setstorage.type: s3 to keep attachments in a bucket you own. This is required for more than one replica, and nothing in the template moves existing attachments between the local volume and the bucket — choose the storage type before uploading content. No attachment volume set is created in this mode.
- AWS S3 (keyless)
- S3-compatible (MinIO and others)
storage.s3.endpoint is set.Create a bucket
storage.s3.bucket and storage.s3.region to match.Set up a cloud account
storage.s3.cloudAccountName to its name.Create a bucket-scoped IAM policy
YOUR_BUCKET_NAME with your bucket), then set storage.s3.policyName to the policy’s name:Leave the key secret empty
storage.s3.auth.secretName empty. The template then attaches the cloud account and your policy to the NocoDB identity.Backing Up
Scheduled backups of the bundled PostgreSQL are off by default. Enable them on whichever database you run —postgres.backup.enabled: true adds the cron workload RELEASE_NAME-postgres-backup; postgresHA.backup.enabled: true adds RELEASE_NAME-postgres-ha-backup. Each run uploads a gzipped SQL dump to your bucket under the configured prefix, covering every base, record, view, and user. Pick a provider and complete the matching setup before installing or upgrading with backups on. The blocks below show the single-instance keys; the HA path takes the same aws / gcp / minio blocks under postgresHA.backup.
- AWS S3
- Google Cloud Storage
- MinIO / S3-compatible
Create a bucket
backup.aws.bucket and backup.aws.region to match.Set up a cloud account
backup.aws.cloudAccountName to its name.Create a bucket-scoped IAM policy
backup.aws.policyName to its name.postgresHA.backup.mode selects logical (a scheduled dump on postgresHA.backup.logical.schedule, using postgresHA.backup.logical.image) or wal-g (continuous WAL archiving every postgresHA.backup.walg.intervalSeconds). On the single-instance path the postgres.backup.image tag must match the PostgreSQL major in postgres.image — change both together if you move off the default.
Three things the database dump does not cover: local attachments live on the RELEASE_NAME-nocodb-storage volume set (S3 attachments are already in your bucket), the Redis data is a cache and job stream that rebuilds itself, and your two keys live in the secret you created. The PostgreSQL volume set (RELEASE_NAME-pg-vs or RELEASE_NAME-postgres-ha-vs) takes no scheduled snapshots; a final snapshot is taken when the volume set is deleted and kept 7 days.
Restoring a Backup
Each single-instance backup is a gzipped plain-SQL dump. Restoring means replaying that SQL into the bundled PostgreSQL. The one transport that carries a dump into the container intact iscpln workload exec with --stdin and a base64 wrapper on both ends — raw binary piped through exec is corrupted:
CREATE ROLE and CREATE DATABASE statements, so a straight replay collides with the database NocoDB already created and migrated on first boot; and no NocoDB replica may be connected while you drop and recreate that database before the replay. For the HA database, follow the restore procedure on the postgres-highly-available page against RELEASE_NAME-postgres-ha-proxy.
Upgrading from 1.0.x
Version 1.1.0 adopted thepostgres 3.4.1 template, which stopped taking database credentials as values. postgres.config.username, .password and .database were removed: put the values your single-instance database was initialized with into the database credentials secret under Prerequisites (keys username, password, database), set postgres.config.credentialsSecretName to its name, and remove the three keys.
Keep the same values so the running database still matches. A values file that still carries an old key fails the render with the postgres template’s message — config.username was REMOVED in postgres 3.4.0 — which tells you to create a dictionary secret; that is correct here too. postgres.backup.minio.accessKey and postgres.backup.minio.secretKey were removed the same way: that path now reads a dictionary secret named by postgres.backup.minio.credentialsSecretName (see Backing Up).
Version 1.0.1 also moved the bundled postgres-highly-available template to 2.4.2, which turns on etcd history compaction. HA installs still on 1.0.0 should upgrade; compaction stops further growth but cannot shrink a backend that has already grown.
If you run the HA database, continue with the section below as well.
Upgrading from 1.1.x
Version 1.2.0 adoptedpostgres-highly-available 2.5.0, which no longer creates its own credentials secret, and the postgresHA.postgres.* keys were removed. Put postgresHA.postgres.username, .password and .database unchanged into the database credentials secret under Prerequisites, set postgresHA.config.credentialsSecretName to its name, and delete the postgresHA.postgres block — the running Patroni cluster was initialized with those values, and the database does not pick up a new password from a secret change. Version 1.2.1 removed postgresHA.backup.minio.accessKey and postgresHA.backup.minio.secretKey the same way; that path now reads postgresHA.backup.minio.credentialsSecretName.
helm upgrade after an install can restart the bundled Redis even when nothing about Redis changed, and NocoDB exits and restarts rather than reconnecting — at a single replica that is a brief outage on a routine config change; a second replica absorbs it. Later upgrades of the same release do not restart Redis.Upgrading from 1.3.x
Version 1.4.0 removedpostgres.credentials: the database credentials are now a prerequisite secret, the same one the database templates require on their own. redis.auth.password was removed the same way: the Redis password is now a prerequisite secret named by redis.credentialsSecretName. Carrying either old key forward fails the render.
1.3.x created the database secret itself, so this upgrade deletes it. Before upgrading, create a secret under a new name holding the values your database was initialized with — not new ones, or NocoDB loses its database connection:
RELEASE_NAME-nocodb-creds (key redisPassword), which this upgrade deletes too. Create the Redis secret under a different name, holding the current Redis password:
postgres.config.credentialsSecretName (single-instance mode) or postgresHA.config.credentialsSecretName (HA mode) set to the database secret’s name, redis.credentialsSecretName set to the Redis secret’s name, and postgres.credentials and redis.auth removed. Your current values are also in postgres.credentials and redis.auth.password of the 1.3.x release.
The upgrade restarts the bundled PostgreSQL and Redis too (they now read the new secrets), so NocoDB can briefly lose its database and Redis; it recovers by itself. While access to the new secrets propagates, the new version of a workload can wait in get-deployments reporting that it is not allowed to reveal the secret; the previous version keeps serving meanwhile, and it clears by itself.
Upgrading from 1.4.0 or earlier
1.4.1 moves the HA database (postgresHA) to controlplanecorporation/patroni-postgres:0.8, which carries pgvector 0.8.7 (CVE-2026-103484). The fix takes effect when the upgrade restarts the Patroni members; existing data needs nothing. Nothing limits that rollout, so expect a brief interruption of writes while the leader changes. NocoDB itself restarts as on any upgrade, and its bundled Redis restarts with it; with a single NocoDB replica (the default) that is the longer interruption, because the old replica stops before the new one serves. Upgrade in a quiet window. If you pinned postgresHA.image in your values, set it to the 0.8 tag: tags 0.1 to 0.7 are refused at render. NocoDB does not use the vector extension; if you created it yourself in a database, \dx keeps reporting the old version until you run ALTER EXTENSION vector UPDATE; there, which only updates that record. Single-instance mode (postgres) is unchanged.
Rotating the Database Password
PostgreSQL keeps the password it was initialized with, and a running workload keeps the values it started with, so editing the secret alone does not change the database password. Change one key and keep the others with export, edit, apply (letters, digits,- and _ only):
- Change it in the database:
ALTER ROLE DB_USERNAME PASSWORD 'NEW_PASSWORD';(connected as that user, from inside the GVC). - Update the secret as above.
- Right away, redeploy NocoDB, and wait until
get-deploymentsshows a higher version number, alone and ready (right after the command the status may not show the restart yet, andready: truealone can still describe the old replica). Do not redeploy the database: PostgreSQL reads the secret only when it is first initialized, so restarting it only adds downtime.
ALTER ROLE; new ones fail until its redeploy finishes, so redeploy right away and rotate in a quiet window.
HA mode needs its own order. The replication role repl shares the password, and a member that restarts with the old password can be promoted to leader, which splits the cluster. Move the leader to member -0 first, so it restarts last, after every other member already has the new password. pgx runs a command in one member (LOCATION is your GVC’s location, DB_USERNAME the secret’s username):
RELEASE_NAME-nocodb, which keeps the old password until it restarts. The app cannot open new database connections from the ALTER ROLE until its own redeploy finishes, so rotate in a quiet window. If a member stays starting, or running without streaming, re-copy it from the leader. This copies the whole database, so it costs network traffic in proportion to its size:
Rotating the Redis Password
Redis keeps no password on disk: it takes the password from the secret each time it starts, and NocoDB does the same. So rotation is the secret and then both restarts:- Update the secret with export, edit, apply as above (letters, digits,
-and_only), and check the new value withcpln secret reveal SECRET_NAME -o yaml. - Redeploy Redis and NocoDB together. Neither picks up the change without its redeploy:
Scaling and Availability
nocodb.replicas sets how many NocoDB replicas run. Replicas coordinate through the bundled Redis, which carries the job and event pub/sub, the shared metadata cache, and the rate limiter — all three are what make a second replica correct rather than merely present. Rolling upgrades proceed one replica at a time.
POST /jobs/listen) backed by the Redis pub/sub, not over websockets — a stalled live update is a Redis or /jobs/listen problem. The database tier scales separately: postgresHA.enabled: true (with postgres.enabled: false) replaces the single PostgreSQL with a 3-replica Patroni cluster behind an HAProxy leader endpoint, and postgresHA.replicas sets the Patroni replica count. The bundled Redis is single-instance by design — NocoDB speaks only a plain redis:// URL, so the Sentinel-based Redis template is not used.
Troubleshooting
Deployment never becomes ready and the logs are empty
Deployment never becomes ready and the logs are empty
cpln helm install reported success, cpln logs returns nothing, and cpln workload get-deployments RELEASE_NAME-nocodb --gvc GVC_NAME -o yaml shows The secret KEYS_SECRET_NAME no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed. under status.versions[].message.Cause: The key secret named by secrets.name, the database credentials secret or the Redis secret (redis.credentialsSecretName) does not exist. The same applies to an admin.secretName, storage.s3.auth.secretName, or smtp.auth.secretName that was set but never created. Check RELEASE_NAME-nocodb-redis and the database workload the same way.Fix: Create it (see Prerequisites). The deployment recovers on its own once the secret exists; cpln workload force-redeployment RELEASE_NAME-nocodb --gvc GVC_NAME skips the wait.One crash in the logs on a fresh install
One crash in the logs on a fresh install
Connection terminated unexpectedly (or an [ioredis] write error) and exits once before coming up clean.Cause: The replica started before PostgreSQL or Redis was accepting connections. It restarts automatically and runs its migrations on the retry.Fix: None needed. One such restart on a first install is expected; a replica that keeps restarting is a different problem — check that the database and Redis secret values use only letters, digits, -, and _.Brief outage on the first helm upgrade
Brief outage on the first helm upgrade
helm upgrade that changed nothing about Redis makes the endpoint return 503 briefly, and the NocoDB logs show an ioredis error followed by an exit.Cause: The first upgrade after an install can restart the bundled Redis, and NocoDB exits rather than reconnecting. It is restarted automatically.Fix: Nothing to repair. Run nocodb.replicas: 2 (with S3 storage) if a single-replica interruption on the first upgrade is unacceptable; later upgrades of the same release do not restart Redis.Render fails because replicas above 1 require s3 storage
Render fails because replicas above 1 require s3 storage
nocodb: nocodb.replicas > 1 requires storage.type: s3 — local attachments live on a per-replica volumeset and would 404 across replicas.Cause: nocodb.replicas is above 1 while storage.type is local.Fix: Complete Attachment Storage on S3 and set storage.type: s3, or keep a single replica.Render fails because static keys are only for S3-compatible servers
Render fails because static keys are only for S3-compatible servers
nocodb: static keys (storage.s3.auth.secretName) are only for S3-compatible servers (storage.s3.endpoint set).Cause: storage.s3.auth.secretName is set without a storage.s3.endpoint. AWS S3 is keyless-only in this template.Fix: For AWS, clear storage.s3.auth.secretName and set storage.s3.cloudAccountName and storage.s3.policyName. For an S3-compatible server, set storage.s3.endpoint too.Render fails asking you to enable exactly one database
Render fails asking you to enable exactly one database
nocodb: enable exactly one database — set either postgres.enabled (single instance, default) or postgresHA.enabled (highly available), not both.Cause: postgres.enabled and postgresHA.enabled are both true, or both false.Fix: To use the HA database set postgresHA.enabled: true and postgres.enabled: false; otherwise leave both at their defaults.Upgrade from 1.0.x fails asking you to create a dictionary secret
Upgrade from 1.0.x fails asking you to create a dictionary secret
config.username was REMOVED in postgres 3.4.0 and advice about a prerequisite dictionary secret.Cause: Your values file still carries postgres.config.username, postgres.config.password, or postgres.config.database.Fix: Move their values into the database credentials secret as described in Upgrading from 1.0.x. If your values carry postgres.credentials or redis.auth.password, follow Upgrading from 1.3.x.Webhook to another workload in the GVC is refused
Webhook to another workload in the GVC is refused
http://WORKLOAD_NAME.GVC_NAME.cpln.local never fires, and the hook log says to set NC_ALLOW_LOCAL_HOOKS=true.Cause: NocoDB’s SSRF guard refuses webhooks to private-network addresses by default, and same-GVC hostnames resolve to private IPs.Fix: Set nocodb.allowLocalWebhooks: true and upgrade. Leave it off if your webhooks only ever call the public internet.Attachment upload rejected with 413 File too large
Attachment upload rejected with 413 File too large
413 and {"message": "File too large", "error": "Payload Too Large", "statusCode": 413}.Cause: The file exceeded storage.fileUploadSizeLimit (a byte count; the default 20971520 is 20 MiB).Fix: Raise storage.fileUploadSizeLimit, upgrade, and upload the file again.Invitations or password-reset emails never arrive
Invitations or password-reset emails never arrive
smtp.enabled is false, or smtp.auth.secretName names a secret that does not exist.Fix: Configure Email with smtp.enabled: true (and smtp.auth.secretName for an authenticated relay), then re-send the invitation.Super-admin password reverts after a restart
Super-admin password reverts after a restart
admin.secretName is set, and NocoDB re-applies NC_ADMIN_EMAIL and NC_ADMIN_PASSWORD from that secret on every boot.Fix: Either clear admin.secretName after the first boot, or change the password in the secret (then run cpln workload force-redeployment RELEASE_NAME-nocodb --gvc GVC_NAME so the new value is picked up) and treat the secret as the source of truth.Important Notes
- Create the key, database credentials and Redis secrets before installing —
secrets.namemust name an existing dictionary secret holdingNC_AUTH_JWT_SECRETandNC_CONNECTION_ENCRYPT_KEY. A missing secret wedges the deployment silently;status.versions[].messageincpln workload get-deployments RELEASE_NAME-nocodb --gvc GVC_NAME -o yamlnames it. - Both keys are write-once — rotating
NC_AUTH_JWT_SECRETlogs out every user, and changingNC_CONNECTION_ENCRYPT_KEYmakes the stored credentials of external data sources undecryptable. Back both values up outside Control Plane. - Sign up immediately after install — signup is open by default, so the first visitor to sign up becomes the super admin. Then turn on invite-only in Team & Settings.
- With SMTP off, invitations and password resets cannot be delivered — configure
smtp.*before inviting collaborators. nocodb.replicasabove1requiresstorage.type: s3— local attachments are per-replica; the chart refuses to render the combination.- AWS S3 is keyless only — a cloud account plus a bucket-scoped IAM policy; static keys are accepted only with an S3-compatible
storage.s3.endpoint. storage.fileUploadSizeLimitis a byte count — the default20971520is 20 MiB; over-limit uploads are rejected with413, not truncated.- Webhooks to same-GVC targets are blocked by default — set
nocodb.allowLocalWebhooks: trueto fire webhooks at other workloads in your GVC. admin.secretNamere-applies on every boot — a password changed in the UI reverts at the next restart. Leave it empty or treat the secret as the source of truth.- Database and Redis credentials use only letters, digits,
-, and_— they are embedded in connection URLs. Rotating the database password needsALTER ROLEplus a forced redeployment of NocoDB; rotating the Redis password needs a forced redeployment of both Redis and NocoDB — see Rotating the Database Password and Rotating the Redis Password. - Enable exactly one database —
postgres(PostgreSQL 18, default) orpostgresHA(PostgreSQL 17). Choose before you have data; switching is a dump and restore. - Give each release its own database and Redis secrets — secret names are org-wide, so two releases pointed at one secret share a password.
- Set
nocodb.siteUrlwhen NocoDB sits behind a custom domain, with the scheme — it drives invitation and password-reset links and the auth cookie’s secure flag. - Background jobs are in-process — a long import, export, or base duplication does not survive the replica running it and must be re-run.
- Uninstalling deletes the volume sets and every base and local attachment in them; your prerequisite secrets are yours and survive.
- MCP endpoints are created per base in the UI (base → Settings → MCP Server) and authenticate with an
xc-mcp-token; account-level MCP and OAuth are Enterprise features and are not available on this edition. - SSO/SAML/OIDC, audit logs, and row-level security are Enterprise features — they ship in the same image but need a purchased licence key that this template never sets.
- NocoDB Community Edition is fair-code — the Sustainable Use License permits self-hosting for your own use; offering NocoDB as a hosted service to others requires a commercial licence.