Skip to content
Klutch.sh Docs

Deploying a NocoDB App

Introduction

NocoDB is an open-source Airtable alternative that turns any database into a smart spreadsheet interface. Deploying NocoDB with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for metadata and uploads—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample API usage, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your NocoDB Dockerfile (GitHub is the only supported git source)
  • Database (PostgreSQL/MySQL/SQLite); for production, use Postgres or MySQL deployed as a Klutch.sh TCP app on port 8000
  • Domain and TLS for secure access

For onboarding, see the Quick Start.

Architecture and ports

  • NocoDB serves HTTP on internal port 8080; choose HTTP traffic.
  • Persistent storage is required for metadata and file uploads.
  • External DB is recommended for production; SQLite is available for small deployments.

Repository layout

nocodb/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub:

Terminal window
docker build -t nocodb-local .
docker run -p 8080:8080 nocodb-local

Dockerfile for NocoDB (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM nocodb/nocodb:latest


ENV NC_PORT=8080


EXPOSE 8080
CMD ["node", "index.js"]

Notes:

  • Pin the image tag (e.g., nocodb/nocodb:0.205.x) for stability and upgrade intentionally.
  • If you add custom plugins or themes, COPY them into the image and ensure dependencies are installed.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • NC_PORT=8080
  • NC_PUBLIC_URL=https://example-app.klutch.sh
  • Database (choose one):
    • Postgres: NC_DB=pg, NC_DB_HOST=<db-host>, NC_DB_PORT=5432, NC_DB_USER=<db-user>, NC_DB_PASSWORD=<db-password>, NC_DB_NAME=<db-name>
    • MySQL: NC_DB=mysql, NC_DB_PORT=3306, plus host/user/password/db
    • SQLite: NC_DB=sqlite, NC_SQLITE_PATH=/usr/app/data/nocodb.db
  • Optional JWT/auth/security: NC_JWT_SECRET=<secure-random>, NC_ENCRYPTION_KEY=<secure-random>

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD=yarn install --frozen-lockfile || npm install && yarn build || npm run build
  • NIXPACKS_START_CMD=node index.js
  • NIXPACKS_NODE_VERSION=18

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /usr/app/data — metadata, SQLite DB (if used), and uploads.
  • /usr/app/logs — optional logs if stored on disk.

Ensure these directories are writable.

Deploy NocoDB on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 8080.
  4. Add the environment variables above, including your database settings and JWT/encryption secrets.
  5. Attach persistent volumes for /usr/app/data (and /usr/app/logs if used), sized for your tables and file uploads.
  6. Deploy. Your NocoDB instance will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

Sample API usage

List tables:

Terminal window
curl -X GET "https://example-app.klutch.sh/api/v1/db/meta/tables" \
  -H "xc-auth-token: <token>"

Create a record (replace table and token):

Terminal window
curl -X POST "https://example-app.klutch.sh/api/v1/db/data/v1/table_name" \
  -H "xc-auth-token: <token>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello from NocoDB","status":"active"}'

Health checks and production tips

  • Add an HTTP probe to / or /api/v1/health for readiness.
  • Enforce HTTPS at the edge; forward internally to port 8080.
  • Use Postgres/MySQL for production; keep DB creds and JWT/encryption keys in Klutch.sh secrets and rotate them regularly.
  • Monitor storage usage on /usr/app/data; resize before it fills.
  • Pin image versions and test upgrades in staging before production.

NocoDB on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, port 8080 configured, and a reliable database, you can deliver a secure, low-code database interface without extra YAML or workflow overhead.