NocoDB Deployment & Usage Guide

1. Prerequisites

Before installing NocoDB, ensure you have the following:

Runtime & Tools:

Docker (recommended for production) or Node.js 18+
Database (choose one):
- PostgreSQL 10+ (recommended for production)
- MySQL 8+
- SQLite (for testing/development only)
- MariaDB 10.5+
- MS SQL Server 2017+
Redis (optional, for caching and job queue)
MinIO/S3-compatible storage (optional, for file attachments)

For Development:

Node.js 18+
npm or yarn
TypeScript 5.0+
Git

Accounts (Optional):

SMTP credentials for email notifications
S3-compatible storage credentials for file attachments
Domain name for SSL setup (if using Auto-upstall)

2. Installation

Docker (Recommended)

With SQLite (Quick Start):

docker run -d \
  --name noco \
  -v "$(pwd)"/nocodb:/usr/app/data/ \
  -p 8080:8080 \
  nocodb/nocodb:latest

With PostgreSQL:

docker run -d \
  --name noco \
  -v "$(pwd)"/nocodb:/usr/app/data/ \
  -p 8080:8080 \
  -e NC_DB="pg://host.docker.internal:5432?u=root&p=password&d=d1" \
  -e NC_AUTH_JWT_SECRET="569a1821-0a93-45e8-87ab-eb857f20a010" \
  nocodb/nocodb:latest

Auto-upstall (Production)

Auto-upstall sets up a complete production stack with PostgreSQL, Redis, MinIO, and Traefik:

bash <(curl -sSL http://install.nocodb.com/noco.sh) <(mktemp)

This script automatically:

Installs Docker and Docker Compose if missing
Sets up NocoDB with PostgreSQL, Redis, MinIO, and Traefik
Configures SSL with automatic renewal
Provides upgrade capability

From Source

# Clone the repository
git clone https://github.com/nocodb/nocodb.git
cd nocodb

# Install dependencies
npm install

# Build the project
npm run build

# Start in development mode
npm run dev

# Or start in production mode
npm start

Binary Downloads (Quick Testing)

macOS (ARM64): curl http://get.nocodb.com/macos-arm64 -o nocodb -L && chmod +x nocodb && ./nocodb
macOS (x64): curl http://get.nocodb.com/macos-x64 -o nocodb -L && chmod +x nocodb && ./nocodb
Linux (ARM64): curl http://get.nocodb.com/linux-arm64 -o nocodb -L && chmod +x nocodb && ./nocodb

3. Configuration

Environment Variables

Database Configuration:

# PostgreSQL
NC_DB="pg://host:port?u=username&p=password&d=database_name"

# MySQL
NC_DB="mysql2://host:port?u=username&p=password&d=database_name"

# SQLite (default)
NC_DB="sqlite:///path/to/nocodb.db"

Authentication & Security:

# JWT Secret (required for production)
NC_AUTH_JWT_SECRET="your-secret-key-here"

# Disable authentication (development only)
NC_DISABLE_AUTH=true

# Admin email and password
NC_ADMIN_EMAIL="admin@example.com"
NC_ADMIN_PASSWORD="your-password"

File Storage:

# Local storage
NC_S3_STORAGE_PATH="./storage"

# S3-compatible storage
NC_S3_BUCKET="your-bucket"
NC_S3_REGION="us-east-1"
NC_S3_ACCESS_KEY="your-access-key"
NC_S3_SECRET_KEY="your-secret-key"
NC_S3_ENDPOINT="https://s3.amazonaws.com"

Email (SMTP):

NC_MAILER_FROM="noreply@example.com"
NC_MAILER_HOST="smtp.example.com"
NC_MAILER_PORT=587
NC_MAILER_SECURE=false
NC_MAILER_USER="username"
NC_MAILER_PASS="password"

Server Configuration:

# Port to listen on
PORT=8080

# Host binding
HOST=0.0.0.0

# Public URL (for links in emails)
NC_PUBLIC_URL="https://your-domain.com"

# Enable/disable signup
NC_AUTH_ALLOW_SIGNUP=true

Configuration Files

NocoDB stores configuration in:

Docker: /usr/app/data/ (mounted volume)
Binary: Current directory
Source: ./packages/nocodb/.env

4. Build & Run

Development Mode

# Clone and setup
git clone https://github.com/nocodb/nocodb.git
cd nocodb

# Install dependencies
npm install

# Start development server
npm run dev

# Access at http://localhost:8080

Production Build

# Build all packages
npm run build

# Start production server
npm start

# Or using PM2 for process management
npm install -g pm2
pm2 start npm --name "nocodb" -- start

Docker Compose (Production)

Create docker-compose.yml:

version: '3.8'

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: nocodb
      POSTGRES_PASSWORD: nocodb_password
      POSTGRES_DB: nocodb
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U nocodb"]
      interval: 10s
      timeout: 5s
      retries: 5

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

  nocodb:
    image: nocodb/nocodb:latest
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    environment:
      NC_DB: "pg://postgres:5432?u=nocodb&p=nocodb_password&d=nocodb"
      NC_REDIS_URL: "redis://redis:6379"
      NC_AUTH_JWT_SECRET: "your-jwt-secret-here"
      NC_PUBLIC_URL: "https://your-domain.com"
    ports:
      - "8080:8080"
    volumes:
      - nocodb_data:/usr/app/data/
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:
  nocodb_data:

Run with:

docker-compose up -d

5. Deployment

Platform Recommendations

Self-Hosted (Recommended):

Docker Swarm/Kubernetes for high availability
Traditional VPS (DigitalOcean, Linode, AWS EC2) with Docker
Bare metal with Node.js runtime

Cloud Platforms:

AWS: ECS/EKS with RDS PostgreSQL and ElastiCache Redis
Google Cloud: GKE with Cloud SQL and Memorystore
Azure: AKS with Azure Database for PostgreSQL and Redis Cache

One-Click Deploy:

DigitalOcean: Marketplace image available
Hetzner: Cloud Console deployment
Render/Yeploy: Docker-based deployment

Kubernetes Deployment

Create nocodb-deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nocodb
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nocodb
  template:
    metadata:
      labels:
        app: nocodb
    spec:
      containers:
      - name: nocodb
        image: nocodb/nocodb:latest
        env:
        - name: NC_DB
          valueFrom:
            secretKeyRef:
              name: nocodb-secrets
              key: database-url
        - name: NC_AUTH_JWT_SECRET
          valueFrom:
            secretKeyRef:
              name: nocodb-secrets
              key: jwt-secret
        ports:
        - containerPort: 8080
        volumeMounts:
        - name: data
          mountPath: /usr/app/data/
        resources:
          requests:
            memory: "512Mi"
            cpu: "250m"
          limits:
            memory: "1Gi"
            cpu: "500m"
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: nocodb-data
---
apiVersion: v1
kind: Service
metadata:
  name: nocodb-service
spec:
  selector:
    app: nocodb
  ports:
  - port: 80
    targetPort: 8080
  type: LoadBalancer

Scaling Considerations

Database: Use managed PostgreSQL (RDS, Cloud SQL) for production
Caching: Redis for session storage and caching
File Storage: S3-compatible storage for attachments
Load Balancing: Use Traefik or Nginx as reverse proxy
Backups: Regular database backups and volume snapshots

6. Troubleshooting

Common Issues

1. Database Connection Errors:

# Check database is accessible
nc -zv database-host 5432

# Verify connection string format
# Correct: pg://host:port?u=user&p=pass&d=database
# Wrong: pg://user:pass@host:port/database

2. Permission Denied on Data Directory:

# Fix permissions for Docker volume
sudo chown -R 1001:1001 ./nocodb-data

# Or set proper permissions in docker-compose
volumes:
  - ./nocodb-data:/usr/app/data/:z  # SELinux context

3. JWT Secret Not Set:

Error: JWT secret must be set for production use

Solution: Set NC_AUTH_JWT_SECRET environment variable with a strong random string.

4. Slow Performance:

Enable Redis caching: NC_REDIS_URL="redis://host:6379"
Optimize PostgreSQL with appropriate indexes
Increase Node.js memory limit: NODE_OPTIONS="--max-old-space-size=4096"

5. Email Not Sending:

Verify SMTP credentials
Check spam folder
Test with NC_MAILER_SECURE=false for non-SSL SMTP
Check firewall allows outbound SMTP traffic

6. File Uploads Failing:

Ensure storage directory is writable
For S3, verify credentials and bucket permissions
Check file size limits (default: 50MB)

7. Auto-upstall SSL Issues:

# Renew SSL certificates manually
docker-compose exec traefik traefik acme renew

# Check Traefik logs
docker-compose logs traefik

8. Development Build Errors:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Check Node.js version (requires 18+)
node --version

# Build specific package
npm run build:gui  # Build frontend only
npm run build:pkg  # Build backend only

Logs & Debugging

Docker Logs:

# View logs
docker logs noco

# Follow logs
docker logs -f noco

# View specific service logs in compose
docker-compose logs nocodb

Enable Debug Mode:

# Set debug environment variable
DEBUG=nocodb:* npm start

# Or for Docker
-e DEBUG="nocodb:*"

Check Health:

# Health endpoint
curl http://localhost:8080/health

# API status
curl http://localhost:8080/api/v1/version

Getting Help

Documentation: https://docs.nocodb.com/
Community: https://community.nocodb.com/
Discord: https://discord.gg/c7GEYrvFtT
GitHub Issues: https://github.com/nocodb/nocodb/issues

When reporting issues, include:

NocoDB version
Database type and version
Deployment method (Docker, binary, source)
Relevant logs (with sensitive information redacted)
Steps to reproduce the issue

How to Deploy & Use nocodb