NocoDB

Deploys NocoDB — an open-source Airtable alternative that turns any database into a smart spreadsheet — via Docker Compose, backed by PostgreSQL.

Requirements

• Docker
• community.docker Ansible collection (>=5.2.0)

Variables

Variable	Default	Description
nocodb_instance	nocodb	Unique instance name. Used as Compose project name and container names.
nocodb_data_path	/data/nocodb	Host path for persistent data (PostgreSQL data, NocoDB attachments/config).
nocodb_docker_path	/docker/nocodb	Host path for the Compose file.
nocodb_image	nocodb/nocodb	NocoDB image. Override for a private mirror/registry.
nocodb_version	2026.08.1	NocoDB image tag. Pin to a specific version in production.
nocodb_pg_version	16	PostgreSQL image tag. Pin to a specific version in production.
nocodb_domain	~	Public domain. When set, enables Traefik routing labels, attaches to traefik_web, and sets NC_SITE_URL.
nocodb_traefik_certresolver	default	Traefik certificate resolver to use for nocodb_domain.
nocodb_port	~	When set, exposes NocoDB on this host port (maps to container port 8080). Omit when using nocodb_domain.
nocodb_pg_user	nocodb	PostgreSQL user, password owner and database name (single value used for all three).
nocodb_pg_pass	~	PostgreSQL password. Required. Generate with: openssl rand -hex 32
nocodb_jwt_secret	~	Signs sessions/API tokens. Required. Set once, never change. Generate with: openssl rand -hex 32
nocodb_invite_only_signup	true	Disables public self-service signup.
nocodb_admin_email	~	Initial super admin email. Optional, must be paired with nocodb_admin_password.
nocodb_admin_password	~	Initial super admin password. Must be ≥8 characters with one uppercase letter, one number, one special char.
nocodb_disable_telemetry	true	Disables anonymous usage telemetry sent to NocoDB.
nocodb_allow_local_external_dbs	false	Allows "External Database" data sources to point at private/local-network hosts. Off by default (SSRF protection).
nocodb_smtp	~	Dict of SMTP settings for invite/password-reset emails. See Usage. Requires nocodb_domain.
nocodb_extra_env	{}	Dict of extra environment variables for the app container (e.g. S3 attachment storage, Redis caching).
nocodb_uninstall	false	Stops and removes containers and the compose directory.
nocodb_purge	false	Also removes the data directory (including the database). Requires nocodb_uninstall: true. Irreversible.

Usage

Minimal setup:

nocodb_pg_pass: "{{ vault_nocodb_pg_pass }}"
nocodb_jwt_secret: "{{ vault_nocodb_jwt_secret }}"
nocodb_domain: "db.example.com"

Without a reverse proxy (direct host port instead of nocodb_domain):

nocodb_port: 8080

Bootstrapping an initial admin account instead of using the first-run signup screen:

nocodb_admin_email: "admin@example.com"
nocodb_admin_password: "{{ vault_nocodb_admin_password }}"

Enabling outgoing mail for invite/password-reset links (requires nocodb_domain):

nocodb_smtp:
  host: mail.example.com
  username: support@example.com
  password: "{{ vault_nocodb_smtp_pass }}"
  from: support@example.com

Connecting an "External Database" data source that lives on this internal network (e.g. another role's Postgres/MySQL instance) instead of the public internet:

nocodb_allow_local_external_dbs: true

Uninstall

To stop and remove all containers and the compose directory:

nocodb_uninstall: true

Add nocodb_purge: true to also delete the database and attachments.

Notes

• Postgres is required, not optional. Without it, NocoDB falls back to an embedded SQLite database, which doesn't scale past a handful of users/tables and complicates backups. It's included by default and not made toggleable. Postgres is only reachable on the internal Docker network — no host port is published.
• nocodb_jwt_secret is permanent. It signs every session and API token. Rotating it after the first deploy immediately logs out every user and invalidates every existing API token. NocoDB will auto-generate a random one on first boot if left unset — this role requires it explicitly instead, so a container recreate doesn't silently generate a new one and kick everyone out.
• nocodb_smtp needs nocodb_domain. SMTP is only useful if the invite/password-reset emails it sends contain a working link, and that link is built from NC_SITE_URL, which this role only sets when nocodb_domain is set. The role enforces this pairing.
• Data directory ownership. {{ nocodb_data_path }}/app (mounted at /usr/app/data, holding attachments and NocoDB's own metadata) is owned by uid/gid 1000, matching the node user NocoDB's image runs as since it moved off root — see nocodb/nocodb#12720.
• Containers are not proxied by Traefik unless nocodb_domain is set — it must already have a traefik_web network and a matching certresolver (see the traefik role).
• nocodb_allow_local_external_dbs is an SSRF trade-off. NocoDB blocks "External Database" sources on private/local addresses by default so a base can't be used to probe or reach other hosts on this network. Only flip it on for an instance whose users are trusted and actually need to connect NocoDB to another internal database.