Getting Started with NocoBase: Install, Configure, and...

Getting Started with NocoBase: Install, Configure, and Build Your First App on a Low-Code Database Platform

NocoBase is a self-hosted, open-source no-code/low-code database platform designed for rapid application development. It is known for being extensible and lightweight.

Prerequisites, Installation, and Environment Setup

This guide will walk you through the step-by-step process of setting up NocoBase, including confirming prerequisites, installing via Docker, configuring the environment, and building your first app with a basic workflow.

Prerequisites Checklist

Set up your environment in minutes. Here’s the essential checklist to make sure Docker-based development runs smoothly across platforms.

Prerequisite	What to do	How to verify
Docker environment	Install Docker Desktop on Windows/macOS or Docker Engine on Linux. Ensure Docker Compose v2+ is available.	Run `docker --version` and `docker compose version` to confirm both are present and up to date.
Hardware resources	Allocate at least 4 GB RAM and 2 CPUs to the Docker daemon.	In Docker Desktop, adjust Resources/Memory and CPUS. On Linux, ensure system limits allow the allocation and verify with `docker info` (look for total memory and CPUs).
Command-line workflow & admin access	Have a basic command-line workflow and admin/root access to install packages and edit files.	Try a simple command like `sudo` usage (where applicable) and install a small package to confirm write permissions and access rights. Edit a file with elevated permissions to validate access.
Open host ports	Ensure ports 3000 (frontend) and 5432 (PostgreSQL) or your chosen database port are free on the host.	Check for existing bindings with commands like `netstat -tuln \| grep -E '3000\|5432'` or `lsof -i :3000 -i :5432`. Try starting a small service on those ports if needed to confirm availability.

By the end of this section, you should have:

Docker installed and accessible with Docker Compose v2+ ready to use.
A machine with at least 4 GB of RAM and 2 CPUs allocated to Docker for smooth performance.
Confidence in using the command line with admin rights to install packages and edit files.
Ports 3000 and 5432 (or your database port) unoccupied on the host to avoid conflicts.

Create docker-compose.yml for NocoBase + PostgreSQL

Set up a lean local stack in minutes by grouping NocoBase and PostgreSQL into a single docker-compose file. This guide shows you exactly what to create and how to run it.

What you’ll do:

Create a folder named nocobase-setup.
Add a docker-compose.yml with two services: nocobase and db.

Use the following sample as the extract for your file:


version: '3.8'
services:
  nocobase:
    image: nocobase/nocobase:latest
    ports:
      - '3000:3000'
    depends_on:
      - db
    environment:
      - DATABASE_HOST=db
      - DATABASE_NAME=nocodb
      - DATABASE_USER=nocodb
      - DATABASE_PASSWORD=secret
  db:
    image: postgres:13
    environment:
      - POSTGRES_USER=nocodb
      - POSTGRES_PASSWORD=secret
      - POSTGRES_DB=nocodb
    volumes:
      - nocodb_dbdata:/var/lib/postgresql/data
volumes:
  nocodb_dbdata:

Save the file and proceed to start the stack with docker-compose up -d.

Run and Verify the Installation

In a few commands, you’ll start the services, verify they’re running, and finish the initial setup by creating the admin account.

Start services: Run docker-compose up -d to launch the containers in the background.
Verify running containers: Check what’s up with docker ps. You should see the nocobase container (and any related services) listed as up.
Check logs if needed: If something isn’t right, inspect startup messages with docker-compose logs -f nocobase to spot issues.
Open the app and complete the setup: Open http://localhost:3000 in your browser and follow the initial setup wizard to create the admin account.

First Run and Basic Configuration

Your first run is the onboarding fast lane: set up the admin, wire the database from docker-compose, and launch your first app with a single guided flow.

Create the initial admin user: During the setup wizard, enter your admin details: full name, a valid email, and a strong password. Finish the wizard to create the initial admin account and land in the onboarding console with admin privileges.

Configure database connection settings: If prompted, configure the database connection. Use the docker-compose environment as the source of truth so the values stay consistent with your deployment.

docker-compose variable	UI field	Example
DB_HOST	Host	db
DB_PORT	Port	5432
DB_NAME	Database	app_db
DB_USER	Username	app_user
DB_PASSWORD	Password	••••••••
DB_SSL	SSL	disable

Tip: keep these values in sync with your docker-compose.yml so your local setup mirrors your deployment environment.

Create your first app: From onboarding, choose Create App and provide the app name, template, or stack you want to start with. When prompted for the database, select the existing connection you configured in step 2, or paste the connection details. Use the Test Connection option to verify visibility and permissions, then finish the setup. Your new app will be wired to the database and ready to run.

Build Your First App: Data Model, Workflows, and UI

Define Your Data Model: Projects and Team Members

Think of your data model as the scaffolding for every feature you’ll build. A clean, well-defined shape makes queries predictable, UI components simpler, and integrations smoother. Here’s a lean, developer-friendly layout for two core collections:

Projects Collection

Field	Type	Notes / Constraints
name	text	Required
start_date	date
end_date	date
status	enum	Possible values: Planned, In Progress, Completed
budget	decimal
owner	relation to Team Members	Links to Team Members.id

Team Members Collection

Field	Type	Notes / Constraints
full_name	text
role	text
email	email

Relationship

The Projects.owner field is a reference to a Team Member's id. This creates a one-to-many relationship from Team Members to Projects: one team member can own many projects, and each project has a single owner.

practical-developer-friendly-guide-to-local-database-storage/”>practical example (how it fits together)

Below are simple sample records to illustrate how the relationship works in practice. The owner column in Projects stores the id of a Team Member.

Team Members (sample)

id	full_name	role	email
1	Ava Chen	Product Manager	ava.chen@example.com
2	Jon Reyes	Frontend Engineer	jon.reyes@example.com

Projects (sample)

name	start_date	end_date	status	budget	owner (Team Member id)
Website Redesign	2024-06-01	2024-09-30	In Progress	45000.00	1
Mobile App MVP	2024-07-15	2025-02-28	Planned	120000.00	2

Tips to keep this model healthy as you scale:

Validate that names are present for Projects and that emails are properly formatted for Team Members.
Treat owner as a stable link to a Team Member; if a member leaves, consider a strategy for reassigning or archiving ownership.
Use clear naming and consistent date formats to simplify querying and reporting.

Create Views and Forms

Ship fast, powerful project UIs with three building blocks: a fast List view, a detailed Detail view, and a validation-driven Create/Edit Form—with a quick owner picker to manage relationships in seconds.

List view for Projects

The List view presents key project data at a glance and supports fast filtering and search:

Name	Start Date	End Date	Status	Budget
Project Atlas	2025-01-10	2025-06-30	In Progress	$120,000

Status: All | Planned | In Progress | Completed | On Hold

Date Range: to

Search by Name: Apply Filters

Detail view

The Detail view shows all fields for a selected project, giving you a complete picture at a glance.

Name: Project Atlas
Start Date: 2025-01-10
End Date: 2025-06-30
Status: In Progress
Budget: $120,000
Owner: Alice Johnson

Form view

The Form supports Create and Edit with validations to keep data clean and consistent.

Name:
Start Date:
End Date:
Budget:
Status: Select status (Planned, In Progress, Completed, On Hold)
Owner: Choose owner (Alice Johnson, Bob Smith, Carol Davis)

Notes: The Owner field in the detail view shows the current owner. The form includes a quick relation picker to assign or change an owner during create or edit.

Configure Dashboards and Automations

Dashboards should tell you the state of your projects at a glance, and automations should handle repetitive tasks in the background. This section shows how to visualize progress and automate common project workflows.

Dashboard widgets

Widget	What it shows	Why it helps
Projects by Status (bar chart)	Counts of projects grouped by status (e.g., Backlog, Queued, In Progress, Review, Done).	Gives you a quick sense of bottlenecks and progress across the portfolio.
Upcoming Start Dates (calendar)	Projects with `start_date` values plotted on a calendar or timeline view.	Helps you plan capacity and spot overlapping starts before they cause stress.
Budget vs. Actual (gauge or bullet chart)	Visual comparison of allocated budget versus actual spend and/or burn rate.	Highlights financial deviations early so you can adjust scope or resources.

Automation examples

On status change to In Progress, automatically assign the first available Team Member with a defined ‘Owner’ role.
- Trigger: Project status changes to “In Progress”.
- Conditions: Find team members with role = “Owner” who are currently available/unassigned.
- Action: Assign the first available Owner to the project (and optionally update the project.owner field and notify the member).
- Notes: If no Owner is available, you can either queue the assignment, assign a backup role, or pause the automation for a grace period.
When a project’s start_date equals today, create a simple onboarding task assigned to the owner (add a Tasks sub-collection related to the Project).
- Trigger: start_date is today.
- Condition: Owner exists for the project.
- Action: Create a new task in the project’s Tasks sub-collection with: Title: “Onboarding for [Project Name]”, Assigned to: Owner, Description: “Quick starter steps for the project team”, Due date: start_date (or start_date + a short horizon, e.g., 1 day).
- Notes: Storing tasks as a sub-collection keeps related work neatly organized under the project record.

Implementation tips

Define a clear Owner role and a reliable way to determine availability (e.g., unassigned, not on leave, or workload-based limits).
Test automation rules with a sample project to confirm the trigger fires correctly and the right member is chosen.
Keep onboarding tasks lightweight and reusable across projects; reuse a template task if your platform supports it.
Monitor dashboards for a few cycles after enabling automations to catch edge cases and adjust thresholds (e.g., what counts as “upcoming” start dates).

Real-World Use-Case Workflow: Project Tracker

Meet a tiny but effective software project tracker: five projects, three teammates, a clean ownership map, a simple status flow, and a weekly dashboard that makes progress visible at a glance.

Projects and Owners

Project	Owner	Current Status
Iris UI Redesign	Alex Chen	In Progress
StackAPI v2 Backend	Priya Kapoor	In Progress
Workflow Automation UI	Miguel Santos	In Progress
Charts Dashboard	Alex Chen	Completed
Auth & Security Module	Priya Kapoor	Completed

Status Progression (Start → End)

Iris UI Redesign: Planned → In Progress
StackAPI v2 Backend: Planned → In Progress
Workflow Automation UI: Planned → In Progress
Charts Dashboard: In Progress → Completed
Auth & Security Module: Planned → Completed

Weekly Status Summary Dashboard

The dashboard aggregates status to help leadership and developers gauge progress at a glance. Example snapshot for the week:

Status	Count	Share
In Progress	3	60%
Completed	2	40%
Planned	0	0%

Troubleshooting, Upgrades, and Pricing Considerations

Pros

Self-hosting: Full data control, privacy, and no ongoing licensing fees for the Community Edition.
Open-source base: Editable source code, community-driven enhancements, and flexibility to customize.
Docker-based installs: Provide reproducible environments.

Cons

Self-hosting: Requires server administration, backups, updates, and security monitoring.
Docker dependency: May require occasional container maintenance.
Feature/Support limitations: Some advanced features or formal support may be limited to paid or enterprise offerings; always verify current licensing on the official site.
Initial setup: May be longer than turnkey hosted no-code options; plan for basic server provisioning and a data backup strategy.

Getting Started with NocoBase: Install, Configure, and…