Self-Hosting NocoDB: A Complete Guide to Running an Open-Source Airtable Alternative

Caption: NocoDB turns database-backed records into spreadsheet-style views, forms, APIs, and team workflows that can live on your own server.

#Introduction

NocoDB is an open-source no-code database platform for teams that want spreadsheet-like editing, forms, views, API access, and collaboration without giving every workflow to a hosted SaaS product. It is often described as an Airtable alternative because users can work with rows, fields, filters, relations, and shared views through a friendly browser interface while the operator keeps control of the underlying deployment.

Self-hosting NocoDB is useful when your data belongs beside other internal systems: inventory lists, lightweight CRM records, content planning, operational checklists, customer intake forms, QA tracking, and admin interfaces for small applications. Developers can connect NocoDB to PostgreSQL and expose APIs. Non-developers can work in grid, kanban, gallery, calendar, and form views. Operators can back up the database, restrict network exposure, monitor health, and control upgrades.

This guide installs NocoDB using Docker Compose. The stack includes the NocoDB web/API container, a worker container for background jobs, PostgreSQL for metadata, Redis for caching and jobs, and Nginx with HTTPS in front. By the end, you will have NocoDB available at https://nocodb.example.com, first-user setup guidance, SMTP notes, a backup routine, and a checklist for creating your first base.

#Why Choose NocoDB?

• Spreadsheet interface for real data: Teams can edit tables, sort records, filter views, and create forms without writing a custom admin panel.
• Open-source and self-hostable: The core project is available from the NocoDB GitHub repository and runs well in a containerized VPS deployment.
• PostgreSQL-friendly deployment: The official self-hosting examples use PostgreSQL and Redis, which makes the stack familiar to operators.
• Built-in API access: NocoDB can serve as a quick internal data layer for tools, dashboards, and automations that need REST API access.
• Multiple view types: Grid, kanban, gallery, calendar, and form workflows let different teams interact with the same data in different ways.
• Worker support: A separate worker container can handle background activity such as imports, exports, and automations.
• Good fit for small teams: It is strong for internal apps, team operations, editorial planning, support queues, and low-code prototypes that need more structure than a shared spreadsheet.

NocoDB is not a replacement for disciplined database design, access control, and backups. Treat it as an application sitting on top of your data, not as a reason to skip schema planning or recovery testing.

#Prerequisites

Hardware Recommendations:

• 2 CPU cores and 2 GB RAM for a small team or homelab deployment
• 4 GB RAM if the same VPS also runs other application containers, monitoring, or a reverse proxy
• 20 GB free disk space to start, plus room for PostgreSQL data, attachments, imports, exports, logs, and backups
• SSD-backed storage for PostgreSQL and Docker volumes
• A second server, NAS, or object storage bucket for off-host backups

Software and Accounts:

• Ubuntu 24.04 LTS server with sudo access
• A domain such as nocodb.example.com
• DNS A or AAAA record pointing the hostname to your server
• Docker Engine and the Docker Compose v2 plugin
• Nginx and Certbot for HTTPS
• SMTP credentials if you want invitation and password-reset emails
• A password manager for PostgreSQL credentials, NC_AUTH_JWT_SECRET, NC_CONNECTION_ENCRYPT_KEY, SMTP credentials, and recovery notes

Security Notes:

• Do not publish the NocoDB container directly to the internet. Bind it to 127.0.0.1 and expose only Nginx over HTTPS.
• Set NC_AUTH_JWT_SECRET explicitly. The environment variable is mandatory for production even though NocoDB can generate a random value if it is missing.
• Set NC_SITE_URL to the public HTTPS URL so email links, Swagger URLs, and backend-generated links use the correct host.
• Back up PostgreSQL, Docker volume data, Compose configuration, and secrets together.
• Test a restore before using NocoDB for business-critical data.

Start with an updated host and a basic firewall:

sudo apt update
sudo apt upgrade -y
sudo apt install -y ca-certificates curl gnupg git ufw nginx certbot python3-certbot-nginx openssl

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

#Installation Guide

This deployment keeps the Compose project under /opt/nocodb. Nginx handles public HTTPS and proxies to NocoDB on localhost. PostgreSQL, Redis, and NocoDB application data are stored in Docker-managed volumes.

#1. Install Docker Engine

Install Docker and confirm that Compose v2 is available:

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
newgrp docker

docker --version
docker compose version

If the Docker group is not active in your current shell, log out and back in before continuing.

#2. Create the NocoDB Project Directory

Create a working directory and a local backup staging area:

sudo mkdir -p /opt/nocodb/backups
sudo chown -R "$USER":"$USER" /opt/nocodb
chmod 700 /opt/nocodb/backups
cd /opt/nocodb

Keep the Compose file and environment file readable only by the deployment user because they contain database and application secrets.

#3. Generate Secrets and Create .env

Compose reads .env for variable interpolation. Generate strong values and write the first environment file:

cd /opt/nocodb

POSTGRES_PASSWORD_VALUE="$(openssl rand -base64 36 | tr -d '\n')"
JWT_SECRET_VALUE="$(openssl rand -hex 32)"
CONNECTION_KEY_VALUE="$(openssl rand -hex 32)"

cat > .env <<EOF
COMPOSE_PROJECT_NAME=nocodb
POSTGRES_PASSWORD=${POSTGRES_PASSWORD_VALUE}
NC_AUTH_JWT_SECRET=${JWT_SECRET_VALUE}
NC_CONNECTION_ENCRYPT_KEY=${CONNECTION_KEY_VALUE}
NC_SITE_URL=https://nocodb.example.com
EOF

chmod 600 .env
nano .env

NC_CONNECTION_ENCRYPT_KEY protects stored external database connection credentials. If you later connect NocoDB to external databases, preserve this key with your backups.

#4. Create the Docker Compose File

Create compose.yaml:

services:
  nocodb:
    image: nocodb/nocodb:latest
    restart: unless-stopped
    environment:
      NC_DB: "pg://db:5432?u=nocodb&p=${POSTGRES_PASSWORD}&d=nocodb"
      NC_AUTH_JWT_SECRET: "${NC_AUTH_JWT_SECRET}"
      NC_CONNECTION_ENCRYPT_KEY: "${NC_CONNECTION_ENCRYPT_KEY}"
      NC_SITE_URL: "${NC_SITE_URL}"
      NC_CACHE_REDIS_URL: "redis://redis:6379"
      NC_JOBS_REDIS_URL: "redis://redis:6379"
      NC_DISABLE_MUX: "true"
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - nocodb_data:/usr/app/data
    healthcheck:
      test: ["CMD-SHELL", "wget -q --tries=1 --spider http://localhost:8080/api/v1/health || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 30s

  worker:
    image: nocodb/nocodb:latest
    restart: unless-stopped
    environment:
      NC_DB: "pg://db:5432?u=nocodb&p=${POSTGRES_PASSWORD}&d=nocodb"
      NC_AUTH_JWT_SECRET: "${NC_AUTH_JWT_SECRET}"
      NC_CONNECTION_ENCRYPT_KEY: "${NC_CONNECTION_ENCRYPT_KEY}"
      NC_SITE_URL: "${NC_SITE_URL}"
      NC_CACHE_REDIS_URL: "redis://redis:6379"
      NC_JOBS_REDIS_URL: "redis://redis:6379"
      NC_WORKER_MODE_ENABLED: "true"
    depends_on:
      nocodb:
        condition: service_healthy
    volumes:
      - nocodb_data:/usr/app/data

  db:
    image: postgres:17.10
    restart: unless-stopped
    environment:
      POSTGRES_USER: nocodb
      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
      POSTGRES_DB: nocodb
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U nocodb -d nocodb"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7
    restart: unless-stopped
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  nocodb_data:
  postgres_data:
  redis_data:

The official quickstart uses the same production-shaped idea: NocoDB, a worker, PostgreSQL, and Redis. For production, pin the NocoDB image tag after testing a release.

#5. Start NocoDB

Pull the images and start the stack:

cd /opt/nocodb
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --since=2m nocodb worker

The first boot runs migrations and prepares the workspace. If a container does not become healthy, inspect the NocoDB logs, confirm that the PostgreSQL password in .env is consistent, and verify that Redis is reachable by the service name redis.

Caption: Nginx exposes HTTPS publicly while NocoDB, the worker, PostgreSQL, Redis, and Docker volumes stay on the server.

#6. Configure Nginx and HTTPS

Create /etc/nginx/sites-available/nocodb.example.com:

server {
    listen 80;
    listen [::]:80;
    server_name nocodb.example.com;

    client_max_body_size 100M;

    location / {
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_pass http://127.0.0.1:8080;
    }
}

Enable the site and request a certificate:

sudo ln -s /etc/nginx/sites-available/nocodb.example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d nocodb.example.com

After Certbot finishes, open https://nocodb.example.com. The first user who signs up becomes the super admin, so create that account from a trusted network and store the credentials in your password manager.

#Configuration

#Public URL and Reverse Proxy Headers

Set NC_SITE_URL to the public HTTPS URL:

NC_SITE_URL=https://nocodb.example.com

This value matters for email links, generated backend URLs, and deployments behind a reverse proxy. The Nginx config forwards Host and X-Forwarded-Proto so NocoDB understands the external request context.

If you want invitation and password-reset emails, add the official NC_SMTP_* variables to .env, restart nocodb and worker, then send a test invitation before relying on email-driven workflows.

#Redis and Background Jobs

The stack uses Redis for cache and background job coordination:

NC_CACHE_REDIS_URL=redis://redis:6379
NC_JOBS_REDIS_URL=redis://redis:6379

The worker container uses the same database and Redis settings as the web/API container, then enables worker mode with NC_WORKER_MODE_ENABLED=true. Keep both containers updated together.

#Backups

Back up PostgreSQL, configuration, and the NocoDB application volume:

cd /opt/nocodb
mkdir -p backups
BACKUP_DATE="$(date +%F-%H%M%S)"

docker compose exec -T db pg_dump -U nocodb nocodb > "backups/nocodb-postgres-${BACKUP_DATE}.sql"
tar czf "backups/nocodb-config-${BACKUP_DATE}.tar.gz" compose.yaml .env
docker run --rm \
  -v nocodb_nocodb_data:/data:ro \
  -v "$PWD/backups:/backups" \
  alpine tar czf "/backups/nocodb-data-${BACKUP_DATE}.tar.gz" -C /data .

sha256sum backups/nocodb-*-"${BACKUP_DATE}".* > "backups/nocodb-${BACKUP_DATE}.sha256"

Copy the completed backup set off the server:

rsync -avh /opt/nocodb/backups/ backup-user@backup.example.com:/srv/backups/nocodb/

Practice restoring on a separate host. A restore test should import PostgreSQL, restore the NocoDB data volume, reuse the same .env secrets, start the stack, and verify login, base views, forms, attachments, and API tokens.

#Usage

#First Login Checklist

After HTTPS is working:

• Open https://nocodb.example.com and create the first account from a trusted network.
• Confirm the first user has super admin access.
• Create a small test base with text, number, date, select, and attachment fields.
• Create grid, kanban, and form views for that table.
• Invite one non-admin test user and confirm their permissions.
• Restart nocodb and worker, then confirm the workspace still loads.

#Build a Practical First Base

Start with a low-risk workflow before moving sensitive production records into NocoDB:

1. Inventory: track internal tools, owners, domains, renewal dates, and runbook links.
2. Content planning: manage ideas, status, author, publish date, and review notes.
3. Support triage: collect form submissions, assign owners, and group work by status.
4. Operations checklist: track backups, certificate renewals, maintenance windows, and incident follow-ups.

Keep the first base intentionally small. Use views to show each team only the columns and records they need, then refine permissions and backup procedures before adding more important data.

Caption: NocoDB can connect data, model tables, present useful views, and expose APIs while operators keep backups and access control in mind.

#Screenshots and Visuals

The diagrams in this guide are original planning visuals covering the NocoDB workspace, Docker stack, data workflow, and backup routine.

Caption: A useful NocoDB backup includes PostgreSQL metadata, application data, configuration, secrets, off-server copies, and restore testing.

#Troubleshooting

• NocoDB cannot connect to PostgreSQL: Confirm NC_DB uses the Compose service name db, the username is nocodb, and the password matches POSTGRES_PASSWORD in .env.
• Container health check fails: Run docker compose logs --since=5m nocodb and check whether migrations, Redis, or database connectivity are failing.
• Email links point to the wrong host: Verify NC_SITE_URL=https://nocodb.example.com, restart the stack, and confirm Nginx forwards Host and X-Forwarded-Proto.
• The first user is not the intended admin: Stop public access until ownership is corrected. For new deployments, create the first account immediately from a trusted network.
• Imports or exports do not complete: Check the worker logs and confirm the worker has the same database, Redis, and secret settings as the main container.
• Attachments disappear after recreation: Confirm the nocodb_data volume exists and is included in backups.
• Nginx shows bad gateway: Confirm docker compose ps shows NocoDB healthy and that the Compose port is bound to 127.0.0.1:8080.
• Backups fail with a missing volume name: Run docker volume ls and adjust the docker run -v source if your Compose project name is not nocodb.

#Scaling, Securing, and Next Steps

For a small team, a single VPS with Docker Compose is a reasonable starting point. As usage grows, monitor container health, PostgreSQL disk growth, Redis health, Nginx errors, certificate renewal, backup age, restore tests, and failed login patterns. Keep upgrades deliberate: read release notes, take a backup, pull images, restart the stack, and verify login, views, forms, API access, and attachments.

Security should focus on access boundaries and recovery. Keep .env readable only by the deployment user, require strong super admin credentials, invite users deliberately, restrict API tokens, limit public form exposure, and encrypt off-server backups. If NocoDB contains sensitive internal data, consider a VPN, identity-aware proxy, or stricter firewall policy.

By following this guide, you now have a self-hosted NocoDB deployment with Docker Compose, PostgreSQL, Redis, a worker container, HTTPS, first-login guidance, SMTP notes, health checks, and a backup routine. Next, build one low-risk base, invite a small test group, rehearse a restore, and then decide which internal workflows deserve a no-code interface on infrastructure you control.

#References

• NocoDB Docker Compose quickstart
• NocoDB single-server install documentation
• NocoDB environment variables
• NocoDB quickstart Docker Compose example
• NocoDB GitHub repository