Installation

Simple installation - takes about three minutes!

Prerequisites

Must haves
- node.js >= 12 / Docker
- MySql / Postgres / SQLserver / SQLite Database
Nice to haves
- Existing schemas can help to create APIs quickly.
- An example database schema can be found here.

Quick try

1-Click Deploy to Heroku

Node app / Docker

npx create-nocodb-app

docker run -d --name nocodb -p 8080:8080 nocodb/nocodb:latest

git clone https://github.com/nocodb/nocodb-seed
cd nocodb-seed
npm install
npm start

To persist data in docker you can mount volume at /usr/app/data/ since 0.10.6. In older version mount at /usr/src/app.

Development Setup

If you want to modify the source code,

Start the backend locally

cd packages/nocodb
npm install
npm run watch:run

Start the frontend locally

cd packages/nc-gui
npm install
npm run dev

Open localhost:3000/dashboard in browser

nocodb/packages/nocodb includes nc-lib-gui which is the built version of nc-gui hosted in npm registry.
You can visit localhost:8000/dashboard in browser after starting the backend locally if you just want to modify the backend only.

Production Setup

NocoDB requires a database to store metadata of spreadsheets views and external databases. And connection params for this database can be specified in NC_DB environment variable.

Docker

docker run -d -p 8080:8080 \
    -e NC_DB="mysql2://host.docker.internal:3306?u=root&p=password&d=d1" \
    -e NC_AUTH_JWT_SECRET="569a1821-0a93-45e8-87ab-eb857f20a010" \
    nocodb/nocodb:latest

docker run -d -p 8080:8080 \
    -e NC_DB="pg://host:port?u=user&p=password&d=database" \
    -e NC_AUTH_JWT_SECRET="569a1821-0a93-45e8-87ab-eb857f20a010" \
    nocodb/nocodb:latest

docker run -d -p 8080:8080 \
    -e NC_DB="mssql://host:port?u=user&p=password&d=database" \
    -e NC_AUTH_JWT_SECRET="569a1821-0a93-45e8-87ab-eb857f20a010" \
    nocodb/nocodb:latest

Environment variables

Variable	Mandatory	Comments	If absent
NC_DB	Yes	See our database URLs	A local SQLite will be created in root folder
NC_DB_JSON	Yes	Can be used instead of `NC_DB` and value should be valid knex connection JSON
NC_DB_JSON_FILE	Yes	Can be used instead of `NC_DB` and value should be a valid path to knex connection JSON
DATABASE_URL	No	JDBC URL Format. Can be used instead of NC_DB. Used in 1-Click Heroku deployment
DATABASE_URL_FILE	No	path to file containing JDBC URL Format. Can be used instead of NC_DB. Used in 1-Click Heroku deployment
NC_DASHBOARD_URL	No	Custom dashboard url path	`/dashboard`
NC_TOOL_DIR	No	App directory to keep metadata and app related files	Defaults to current working directory. In docker maps to `/usr/app/data/` for mounting volume.
NC_PUBLIC_URL	Yes	Used for sending Email invitations	Best guess from http request params
NC_AUTH_JWT_SECRET	Yes	JWT secret used for auth and storing other secrets	A Random secret will be generated
NC_JWT_EXPIRES_IN	No	JWT token expiry time	`10h`
NC_CONNECT_TO_EXTERNAL_DB_DISABLED	No	Disable Project creation with external database
NC_INVITE_ONLY_SIGNUP	No	Allow users to signup only via invite url, value should be any non-empty string.
NC_BACKEND_URL	No	Custom Backend URL	`http://localhost:8080` will be used
NC_REQUEST_BODY_SIZE	No	Request body size limit	`1048576`
NC_EXPORT_MAX_TIMEOUT	No	After NC_EXPORT_MAX_TIMEOUT csv gets downloaded in batches	Default value 5000(in millisecond) will be used
DB_QUERY_LIMIT_DEFAULT	No	Default pagination limit	25
DB_QUERY_LIMIT_MAX	No	Maximum allowed pagination limit	100
DB_QUERY_LIMIT_MIN	No	Minimum allowed pagination limit	1
NC_DISABLE_TELE	No	Disable telemetry
NC_GOOGLE_CLIENT_ID	No	Google client id to enable google authentication
NC_GOOGLE_CLIENT_SECRET	No	Google client secret to enable google authentication
NC_MIGRATIONS_DISABLED	No	Disable NocoDB migration
NC_ONE_CLICK	No	Used for Heroku one-click deployment
NC_MIN	No	If set to any non-empty string the default splash screen(initial welcome animation) and matrix screensaver will disable
PORT	No	For setting app running port	`8080`
NC_SENTRY_DSN	No	For Sentry monitoring
NC_DISABLE_ERR_REPORT	No	Disable error reporting
AWS_ACCESS_KEY_ID	No	For Litestream - S3 access key id	If Litestream is configured and NC_DB is not present. SQLite gets backed up to S3
AWS_SECRET_ACCESS_KEY	No	For Litestream - S3 secret access key	If Litestream is configured and NC_DB is not present. SQLite gets backed up to S3
AWS_BUCKET	No	For Litestream - S3 bucket	If Litestream is configured and NC_DB is not present. SQLite gets backed up to S3
AWS_BUCKET_PATH	No	For Litestream - S3 bucket path (like folder within S3 bucket)	If Litestream is configured and NC_DB is not present. SQLite gets backed up to S3

Docker Compose

git clone https://github.com/nocodb/nocodb
cd nocodb
cd docker-compose
cd mysql
docker-compose up

git clone https://github.com/nocodb/nocodb
cd nocodb
cd docker-compose
cd pg
docker-compose up

git clone https://github.com/nocodb/nocodb
cd nocodb
cd docker-compose
cd mssql
docker-compose up

AWS ECS (Fargate)

Create ECS Cluster

aws ecs create-cluster \
--cluster-name <YOUR_ECS_CLUSTER>

Create Log group

aws logs create-log-group \
--log-group-name /ecs/<YOUR_APP_NAME>/<YOUR_CONTAINER_NAME>

Create ECS Task Definiton

Every time you create it, it will add a new version. If it is not existing, the version will be 1.

aws ecs register-task-definition \
--cli-input-json "file://./<YOUR_TASK_DEF_NAME>.json"

This json file defines the container specification. You can define secrets such as NC_DB and environment variables here.

Here's the sample Task Definition

{
    "family": "nocodb-sample-task-def",
    "networkMode": "awsvpc",
    "containerDefinitions": [{
        "name": "<YOUR_CONTAINER_NAME>",
        "image": "nocodb/nocodb:latest",
        "essential": true,
        "logConfiguration": {
            "logDriver": "awslogs",
            "options": {
                "awslogs-group": "/ecs/<YOUR_APP_NAME>/<YOUR_CONTAINER_NAME>",
                "awslogs-region": "<YOUR_AWS_REGION>",
                "awslogs-stream-prefix": "ecs"
            }
        },
        "secrets": [{
            "name": "<YOUR_SECRETS_NAME>",
            "valueFrom": "<YOUR_SECRET_ARN>"
        }],
        "environment": [{
            "name": "<YOUR_ENV_VARIABLE_NAME>",
            "value": "<YOUR_ENV_VARIABLE_VALUE>"
        }],
        "portMappings": [{
            "containerPort": 8080,
            "hostPort": 8080,
            "protocol": "tcp"
        }]
    }],
    "requiresCompatibilities": [
        "FARGATE"
    ],
    "cpu": "256",
    "memory": "512",
    "executionRoleArn": "<YOUR_ECS_EXECUTION_ROLE_ARN>",
    "taskRoleArn": "<YOUR_ECS_TASK_ROLE_ARN>"
}

Create ECS Service

aws ecs create-service \
--cluster <YOUR_ECS_CLUSTER> \
--service-name  <YOUR_SERVICE_NAME> \
--task-definition <YOUR_TASK_DEF>:<YOUR_TASK_DEF_VERSION> \
--desired-count <DESIRED_COUNT> \
--launch-type "FARGATE" \
--platform-version <VERSION> \
--health-check-grace-period-seconds <GRACE_PERIOD_IN_SECOND> \
--network-configuration "awsvpcConfiguration={subnets=["<YOUR_SUBSETS>"], securityGroups=["<YOUR_SECURITY_GROUPS>"], assignPublicIp=ENABLED}" \
--load-balancer targetGroupArn=<TARGET_GROUP_ARN>,containerName=<CONTAINER_NAME>,containerPort=<YOUR_CONTAINER_PORT>

If your service fails to start, you may check the logs in ECS console or in Cloudwatch. Generally it fails due to the connection between ECS container and NC_DB. Make sure the security groups have the correct inbound and outbound rules.